Facebook Messenger chatbots — bots, subscribers, variables, flows and campaigns, with persistent menus and quick replies.
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: API Key
description: >
Static API Key authentication. A long-lived token generated manually in
the SendPulse account settings.
x-ai-description: >
Permanent authentication token. Ideal for simple integrations without
token refresh logic.
outh2:
type: oauth2
description: OAuth 2.0 Client Credentials flow for temporary access tokens.
flows:
clientCredentials:
tokenUrl: https://api.sendpulse.com/oauth/access_token
scopes: {}
x-ai-description: >
Standard OAuth 2.0 flow using Client ID and Client Secret. Provides
temporary tokens (valid for 1 hour) for enhanced security.
schemas:
SuccessResponse:
properties:
success:
type: boolean
data:
anyOf:
- type: array
items:
type: object
- type: object
- type: boolean
type: object
Contact:
properties:
id:
type: string
bot_id:
type: string
status:
type: integer
enum:
- 1
- 2
- 3
description: |2-
* `1` - active
* `2` - unsubscribed
* `3` - disabled
channel_data:
type: object
properties:
id:
type: string
name:
type: string
first_name:
type: string
last_name:
type:
- string
- 'null'
profile_pic:
type:
- string
- 'null'
locale:
type:
- string
- 'null'
gender:
type:
- string
- 'null'
tags:
type: array
uniqueItems: true
items:
type: string
variables:
type: object
description: 'variable_name: variable_value'
is_chat_opened:
type: boolean
last_activity_at:
type: string
example: 2020-12-11T21:00:00.000Z
automation_paused_until:
type:
- string
- 'null'
example: 2020-12-11T21:00:00.000Z
unsubscribed_at:
type:
- string
- 'null'
example: 2020-12-11T21:00:00.000Z
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Flow:
properties:
id:
type: string
bot_id:
type: string
name:
type: string
status:
type: integer
enum:
- 1
- 2
description: |2-
* `1` - active
* `2` - inactive
triggers:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Trigger:
properties:
id:
type: string
bot_id:
type: string
flow_id:
type:
- string
- 'null'
name:
type: string
type:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
description: |2-
* `1` - starts immediately upon subscription
* `2` - starts when unsubscribed
* `3` - default reply
* `4` - starts when the specified keyword is entered
* `5` - starts at the specified time when subscribing
status:
type: integer
enum:
- 1
- 2
description: |2-
* `1` - active
* `2` - inactive
keywords:
type: array
items:
type: string
execution:
type: object
properties:
interval:
type: integer
units:
type: integer
enum:
- 1
- 2
- 3
description: |2-
* `1` - minutes
* `2` - hours
* `3` - days
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Variable:
properties:
id:
type: string
bot_id:
type: string
name:
type: string
description:
type:
- string
- 'null'
type:
type: integer
enum:
- 1
- 2
description: |2-
* `1` - contact variable
* `2` - bot variable
value_type:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
example: 1
description: |2-
this type of variable can have the following values:
* `1` - string
* `2` - number
* `3` - date
* `4` - boolean
* `5` - phone
* `6` - email
* `7` - url
status:
type: integer
enum:
- 1
- 2
description: |2-
* `1` - active
* `2` - trashed
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Campaign:
properties:
id:
type: string
bot_id:
type: string
title:
type: string
message_tag:
type: string
enum:
- HUMAN_AGENT
- CUSTOMER_FEEDBACK
description: ''
example: HUMAN_AGENT
message_notification_type:
type: string
enum:
- REGULAR
- SILENT_PUSH
- NO_PUSH
description: ''
example: REGULAR
send_at:
type: string
example: 2020-12-11T21:00:00.000Z
messages:
type: array
description: A list of messages to send
items:
type: object
properties:
type:
type: string
enum:
- text
- media_img
- media_file
- media_audio
- media_video
- template
- list
description: |
* `text` - text message
example: text
data:
type: object
description: ''
properties:
attachment:
type: object
properties:
payload:
type: object
properties:
elements:
type: array
items:
type: object
properties:
filename:
type: string
is_external_attachment:
type: boolean
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Bot:
properties:
id:
type: string
channel_data:
type: object
properties:
id:
type: string
name:
type: string
photo:
type:
- string
- 'null'
inbox:
type: object
properties:
total:
type: integer
unread:
type: integer
status:
type: integer
enum:
- 3
- 5
description: |2-
* `3` - active
* `5` - inactive
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Chat:
properties:
contact:
$ref: '#/components/schemas/Contact'
inbox_last_message:
$ref: '#/components/schemas/Message'
inbox_unread:
type: integer
Message:
properties:
id:
type: string
contact_id:
type: string
bot_id:
type: string
campaign_id:
type:
- string
- 'null'
data:
type: object
description: >-
https://developers.facebook.com/docs/messenger-platform/reference/send-api/#message
example:
text: hello
direction:
type: integer
enum:
- 1
- 2
description: |2-
* `1` - in
* `2` - out
status:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
description: |2-
* `1` - new
* `2` - sent
* `3` - delivered
* `4` - opened
* `5` - redirected
* `6` - rejected
delivered_at:
type:
- string
- 'null'
example: 2020-12-11T21:00:00.000Z
opened_at:
type:
- string
- 'null'
example: 2020-12-11T21:00:00.000Z
redirected_at:
type:
- string
- 'null'
example: 2020-12-11T21:00:00.000Z
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Account:
properties:
plan:
type: object
description: '`-1` - unlimited'
properties:
code:
type: string
max_bots:
type: integer
max_contacts:
type: integer
example: -1
max_messages:
type: integer
max_tags:
type: integer
max_variables:
type: integer
branding:
type: boolean
is_exceeded:
type: boolean
is_expired:
type: boolean
expired_at:
type: string
example: 2020-12-11T21:00:00.000Z
statistics:
type: object
description: ''
properties:
messages:
type: integer
bots:
type: integer
contacts:
type: integer
variables:
type: integer
Tag:
properties:
id:
type: string
name:
type: string
contact_count:
type: integer
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
info:
description: >-
Using the API for Facebook Messenger chatbots, you can integrate your system
with SendPulse’s chatbots service and get detailed information about your
account, bots, subscribers, variables, flows, and chats. You can also create
campaigns, launch flows, assign and remove variables and tags.
On the right, there is a button for authorizing requests made on this page.
Click “Authorize,” then insert the ID and Secret from your account.
To perform a request directly from the page, click the "Try it out" button
within each method block. Then fill in input fields if any (for URL
parameters, the description is right below the URL request; for body
parameters, the description is under the “Scheme” button to the right of the
example), and click “Run.” You'll find the server response and description
of received parameters below.
title: Facebook Messenger service API
version: 0.0.1
openapi: 3.1.2
paths:
/contacts/get:
get:
summary: Get contact info via a contact ID
description: >-
Returns information on the selected contact: bot and contact ID,
information from Facebook, list of tags and variables, activity data and
date added
security:
- oAuth2ClientCredentials: []
tags:
- contacts
parameters:
- in: query
name: id
required: true
schema:
type: string
description: >-
Contact ID. Can be obtained with a contact search by tag or
variable. You can also find it in your account in the address bar of
a chat window with the desired contact.
responses:
'200':
description: Operation successful
content:
application/json:
schema:
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Contact'
type: object
operationId: getContact
x-ai-role: crm_data_analyst
x-ai-description: >-
Retrieves a complete profile snapshot of a single chatbot contact by
their internal ID. This is the authoritative source for contact state —
combining identity data from the connected platform (e.g. Facebook),
enriched variables, tags, and engagement history. Use this before
personalizing messages or evaluating automation eligibility.
x-ai-reasoning-instructions:
- >-
Ensure the contact ID is valid and was obtained from a prior search or
account UI — it is not the same as a platform user ID.
- >-
If the upstream intent is to personalize a message, fetch this
endpoint first to verify current variable values and tag state.
- >-
If the response returns no data or a 404-equivalent, suggest the user
verify the contact ID or search by tag/variable instead.
x-ai-responding-instructions:
- >-
Surface the most actionable fields first: contact ID, bot ID, tags,
and variables.
- >-
If activity data is present, highlight last-seen or last-interaction
timestamp to give context on contact engagement.
- >-
If the contact has no tags or variables, suggest adding them as a next
step for segmentation.
x-ai-suggestions:
- >-
Use the returned tag list to evaluate which automation flows this
contact is eligible for.
- >-
Cross-reference variables with campaign conditions before triggering a
sequence.
- >-
If you need to find the contact ID, use a contact search by tag or
variable first.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/contacts/getByTag:
get:
summary: Get a list of contacts by tag
description: Returns a list of contacts by tag for the specified bot
security:
- oAuth2ClientCredentials: []
tags:
- contacts
parameters:
- in: query
name: tag
required: true
schema:
type: string
description: created contact’s tag to search by
- in: query
name: bot_id
required: true
schema:
type: string
description: >-
Bot ID. Can be obtained with a method of getting a list of bots. You
can also find it in your account in the address bar of a chat window
with the desired contact.
- in: query
name: size
description: The limit of pagination items, that will be returned
schema:
type: integer
- in: query
name: skip
description: The offset of pagination items, where starts a current items batch
schema:
type: integer
responses:
'200':
description: Operation successful
content:
application/json:
schema:
properties:
success:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/Contact'
type: object
operationId: getContactsByTag
x-ai-role: chatbot_audience_analyst
x-ai-description: >-
Retrieves a filtered subset of bot contacts grouped by a specific tag.
Tags in SendPulse chatbots act as behavioral or segmentation labels
assigned during flows or manually. This endpoint is the primary way to
build targeted audiences for broadcast campaigns, re-engagement flows,
or CRM export — without iterating over the full contact list.
x-ai-reasoning-instructions:
- >-
Before calling, confirm the bot_id is valid by cross-referencing with
the list of available bots.
- >-
Ensure the tag value matches exactly — tags are case-sensitive and
must already exist on at least one contact.
- >-
If the user wants all contacts with a tag, omit 'size' and 'skip' on
first call, then paginate if the result set is large.
- >-
Use 'skip' + 'size' for pagination — calculate total pages based on
result count vs. requested size.
- >-
If 0 contacts are returned, suggest verifying the tag spelling or
checking whether contacts were tagged via the correct flow.
x-ai-responding-instructions:
- >-
Report the number of contacts returned and whether pagination is
likely needed.
- >-
If the list is empty, suggest checking tag assignment logic in the bot
flow.
- >-
Highlight key contact fields (e.g., ID, name, last activity) to orient
the user.
- >-
Suggest follow-up actions such as sending a broadcast to this segment
or exporting to CRM.
x-ai-suggestions:
- >-
Use this endpoint to build a segment before triggering a targeted
broadcast.
- Combine with pagination (size=50, skip=0) for large tag audiences.
- >-
Tag names like 'vip', 'trial_expired', or 'webinar_registered' are
common segmentation patterns.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/contacts/getByVariable:
get:
summary: Get a list of contacts by variable
description: >-
Returns a list of contacts by variable identifier or variable name for
the specified bot
security:
- oAuth2ClientCredentials: []
tags:
- contacts
parameters:
- in: query
name: variable_id
schema:
type: string
description: Contact's variable ID
- in: query
name: variable_name
schema:
type: string
description: Сontact variable name to search by
- in: query
name: bot_id
schema:
type: string
description: >-
Bot ID. Can be obtained with a method of getting a list of bots. You
can also find it in your account in the address bar of a chat window
with the desired contact.
- in: query
name: variable_value
required: true
schema:
type: string
description: Contact's variable value
- in: query
name: size
description: The limit of pagination items, that will be returned
schema:
type: integer
- in: query
name: skip
description: The offset of pagination items, where starts a current items batch
schema:
type: integer
responses:
'200':
description: Operation successful
content:
application/json:
schema:
properties:
success:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/Contact'
type: object
operationId: getContactsByVariable
x-ai-role: chatbot_crm_specialist
x-ai-description: >-
Enables targeted lookup of bot contacts by a specific variable value —
useful for segmentation, personalization pipelines, and triggering flows
based on contact attributes. Unlike a general contact list, this
endpoint finds contacts who match a precise data condition (e.g., all
contacts where `plan = 'pro'` or `city = 'Kyiv'`), making it essential
for data-driven automation.
x-ai-reasoning-instructions:
- >-
Either `variable_id` or `variable_name` must be provided alongside
`variable_value` — clarify with the user if both are missing.
- >-
If `bot_id` is not provided, ask the user to specify which bot to
search in, since variables are bot-scoped.
- >-
Use `size` and `skip` for paginated retrieval when the result set may
be large; default page size is usually 10–25.
- >-
Variable names and values are case-sensitive — confirm exact casing
with the user if no results are returned.
- >-
If the user wants to find contacts for a campaign segment, suggest
chaining this with a messaging or tagging operation.
x-ai-responding-instructions:
- Report how many contacts were found matching the variable condition.
- >-
If the result is empty, suggest verifying the variable name/value
spelling or checking if the variable exists for that bot.
- >-
If pagination was used, remind the user that more records may exist
and suggest incrementing `skip`.
- >-
Highlight key contact identifiers (e.g., contact ID, name) from the
result to help the user proceed.
x-ai-suggestions:
- >-
Search by `variable_name=plan` and `variable_value=premium` to find
premium subscribers.
- Use `skip=0&size=50` for the first page of results.
- >-
Chain with a send-message endpoint to target the returned contacts
directly.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/contacts/sendText:
post:
summary: Send a text message to a contact
description: Sends a text message to the specified contact
security:
- oAuth2ClientCredentials: []
tags:
- contacts
requestBody:
description: ''
required: true
content:
application/json:
schema:
properties:
contact_id:
type: string
description: >-
Contact ID. Can be obtained with a contact search by tag or
variable. You can also find it in your account in the
address bar of a chat window with the desired contact.
message_type:
type: string
enum:
- MESSAGE_TAG
- RESPONSE
description: ''
example: RESPONSE
message_tag:
$ref: '#/components/schemas/Campaign/properties/message_tag'
text:
type: string
description: >-
Message text to send, maximum characters -, may include
emoji
required:
- contact_id
- message_type
- tag
- text
responses:
'200':
description: Operation successful
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
operationId: sendTextToContact
x-ai-role: chatbot_communication_specialist
x-ai-description: >-
Sends a direct text message to a specific contact within a chatbot
conversation. This is a real-time messaging action — the message is
delivered immediately to the contact's chat window. The message_type
field controls whether this is a free-form reply (RESPONSE, valid within
the 24-hour messaging window) or a pre-approved template outside that
window (MESSAGE_TAG). Choosing the wrong type will result in a policy
violation or delivery failure.
x-ai-reasoning-instructions:
- >-
Verify that contact_id is valid and belongs to an active contact — use
contact search by tag or variable if needed.
- >-
Check message_type: use RESPONSE only if the contact has sent a
message within the last 24 hours; otherwise use MESSAGE_TAG with an
appropriate tag.
- >-
If message_type is MESSAGE_TAG, ensure message_tag is provided and
corresponds to an approved use case.
- >-
Validate that the text does not exceed the platform character limit
and is properly encoded (emoji are supported).
- >-
Do not send sensitive data (passwords, tokens, PII) as plain text in
the message body.
x-ai-responding-instructions:
- >-
Confirm the message was sent successfully and mention the contact_id
it was delivered to.
- >-
If message_type was MESSAGE_TAG, note which tag was used for auditing
purposes.
- >-
If the request fails due to a 24-hour window constraint, suggest
switching to MESSAGE_TAG with a suitable tag.
- >-
If contact_id is not found, recommend using the contact search
endpoint to retrieve the correct ID.
x-ai-suggestions:
- Use RESPONSE type for replies within active conversation windows.
- >-
Use MESSAGE_TAG with 'POST_PURCHASE_UPDATE' for order-related
follow-ups outside the 24h window.
- >-
Combine with contact search endpoints to dynamically resolve
contact_id before sending.
x-ai-capabilities:
confirmation:
type: Recommended
message: >-
You are about to send a message directly to a contact. Confirm the
text content and recipient before proceeding.
security_info:
data_handling:
- ExternalDelivery
- UserFacing
/contacts/send:
post:
summary: Send message to a contact
description: Sends message to the specified contact
security:
- oAuth2ClientCredentials: []
tags:
- contacts
requestBody:
description: ''
required: true
content:
application/json:
schema:
properties:
contact_id:
type: string
description: >-
Contact ID. Can be obtained with a contact search by tag or
variable. You can also find it in your account in the
address bar of a chat window with the desired contact.
message:
properties:
type:
type: string
enum:
- UPDATE
- RESPONSE
- MESSAGE_TAG
description: ''
example: RESPONSE
tag:
type: string
enum:
- HUMAN_AGENT
- CUSTOMER_FEEDBACK
description: ''
example: HUMAN_AGENT
content_type:
type: string
enum:
- message
- media_img
- media_file
- template
description: Type of data sent
example: message
text:
type: string
description: >-
The parameter is required if the `content_type`
parameter is equal to `message`
example: Hello world!
img:
type: sting
description: >-
The parameter is required if the `content_type`
parameter is equal to `media_img`
example: >-
https://www.spcdn.org/images/promo-logo/correct/sendpulse-logo-13.png
file:
type: string
description: >-
The parameter is required if the `content_type`
parameter is equal to `media_file`
example: >-
https://www.spcdn.org/images/promo-logo/correct/sendpulse-logo-13.png
data:
type: object
description: >-
The paramater is required if the `content_type`
paramater is equal to `template`
properties:
attachment:
type: object
properties:
type:
type: string
enum:
- template
payload:
type: object
properties:
template_type:
type: string
enum:
- generic
elements:
type: array
items:
type: object
properties:
title:
type: string
subtitle:
type: string
image_url:
type: string
example: >-
https://www.spcdn.org/images/promo-logo/correct/sendpulse-logo-13.png
buttons:
type: array
items:
type: object
properties:
type:
type: string
enum:
- web_url
- postback
# --- truncated at 32 KB (155 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-facebook-openapi.yml