WhatsApp Business chatbots — bots, subscribers, variables, flows, campaigns, chats and pre-approved template messages.
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
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
Bot:
properties:
id:
type: string
channel_data:
type: object
properties:
name:
type: string
phone:
type: integer
inbox:
type: object
properties:
total:
type: integer
unread:
type: integer
status:
type: integer
enum:
- 3
- 4
description: |2-
* `3` - active
* `4` - inactive
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Contact:
properties:
id:
type: string
bot_id:
type: string
status:
type: integer
enum:
- 1
- 2
- 3
- 4
description: |2-
* `1` - active
* `2` - unsubscribed
* `3` - disabled
* `4` - blocked by user
channel_data:
type: object
properties:
username:
type:
- string
- 'null'
first_name:
type: string
last_name:
type:
- string
- 'null'
name:
type: string
language_code:
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
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:
CONTACT: 1
description: |2-
* `1` - contact variable
* `2` - bot variable
value_type:
type: integer
example: 1
enum:
STRING: 1
NUMBER: 2
DATE: 3
BOOLEAN: 4
PHONE: 5
EMAIL: 6
URL: 7
LOCATION: 8
DATETIME: 9
TIME: 10
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:
ACTIVE: 1
TRASHED: 2
description: |2-
* `1` - active
* `2` - trashed
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:
- ACTIVE: 1
INACTIVE: 2
DRAFT: 4
description: |2-
* `1` - active
* `2` - inactive
triggers:
type: array
items:
type: object
properties:
id:
type: string
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
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:
ACTIVE: 1
INACTIVE: 2
description: |2-
* `1` - active
* `2` - inactive
keywords:
type: array
items:
type: string
execution:
type: object
properties:
interval:
type: integer
units:
type: integer
enum:
MINUTES: 1
HOURS: 2
DAYS: 3
description: |2-
* `1` - minutes
* `2` - hours
* `3` - days
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Campaign:
properties:
id:
type: string
bot_id:
type: string
title:
type: string
send_at:
type: string
example: 2020-12-11T21:00:00.000Z
messages:
type: array
items:
type: object
cost:
type: object
properties:
amount:
type: number
example: 0.56
currency:
type: string
example: USD
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://core.telegram.org/bots/api#message
example:
text: hello
direction:
type: integer
enum:
IN: 1
OUT: 2
description: |2-
* `1` - in
* `2` - out
status:
type: integer
enum:
- 1
description: |2-
* `1` - new
* `2` - sent
* `3` - delivered
* `4` - opened
* `5` - redirected
* `6` - rejected
is_paid:
type: boolean
price_cbp:
type:
- object
- 'null'
description: Conversation Based Price
example:
price: 0.006
currency: USD
origin_type: user_initiated
is_free_conversation: false
country_code: TR
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
Template:
properties:
id:
type: string
bot_id:
type: string
namespace:
type: string
category:
type: string
components:
type: array
description: >-
Please see
https://developers.facebook.com/docs/whatsapp/api/messages/message-templates/media-message-templates/
items:
type: object
language:
type: string
name:
type: string
rejected_reason:
type:
- string
- 'null'
status:
type: string
enum:
- APPROVED
- IN_APPEAL
- PENDING
- REJECTED
- PENDING_DELETION
- DELETED
- DISABLED
- PAUSED
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
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 WhatsApp 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: WhatsApp service API
version: 0.0.1
openapi: 3.1.2
paths:
/contacts:
post:
summary: Create new contact
description: Creates a new contact in the audience of the selected bot
security:
- oAuth2ClientCredentials: []
tags:
- contacts
requestBody:
description: ''
required: true
content:
application/json:
schema:
properties:
phone:
type: string
description: Phone number in international format
name:
type: string
description: Contact name
bot_id:
type: string
description: Bot's ID to which you add a contact
tags:
type: array
description: List of tags to assign to the contact
items:
type: string
variables:
type: array
description: >-
The set of additional parameters differs depending on the
included template components and can include variables, an
image, or a file.
items:
type: object
properties:
name:
type: string
description: Name of the variable
value:
OneOf:
- type: string
description: The value that is set for the variable
- type: integer
description: The value that is set for the variable
required:
- phone
- bot_id
responses:
'200':
description: Operation successful
content:
application/json:
schema:
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Contact'
type: object
operationId: createContact
x-ai-role: chatbot_audience_manager
x-ai-description: >-
Registers a new contact in the bot's audience, establishing the
foundational subscriber record. In SendPulse, a contact is not merely a
phone number — it is a stateful entity tied to a specific bot, enriched
with tags and custom variables that drive personalization, segmentation,
and automated flow targeting.
x-ai-reasoning-instructions:
- >-
Always confirm the bot_id exists and belongs to the user's account
before attempting to create a contact.
- >-
Phone number must be in international format (e.g., +14155552671) —
validate the format before submission.
- >-
Check whether a contact with the same phone number already exists in
the specified bot's audience to avoid duplicates.
- >-
If tags are provided, ensure they follow the bot's existing tag
taxonomy for consistent segmentation.
- >-
Variables should be validated against the bot's defined variable
schema — mismatched names will be silently ignored.
x-ai-responding-instructions:
- >-
Confirm successful creation by referencing the new contact's ID from
the returned Contact object.
- >-
If the phone number is already registered in that bot's audience,
clarify whether an update or merge is needed instead.
- >-
Suggest assigning the contact to a flow or sending an initial message
as the logical next step.
- >-
If creation fails due to bot_id not found, prompt the user to retrieve
available bots first.
x-ai-suggestions:
- >-
After creation, use `sendMessage` or trigger a flow to engage the
contact immediately.
- >-
Use tags like 'new_lead', 'vip', or 'opt-in-web' for downstream
segmentation.
- >-
Store CRM identifiers in variables (e.g., `crm_id`) to link contacts
across systems.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- PII
- ResourceStateUpdate
/contacts/get:
get:
summary: Get contact info via a contact ID
description: >-
Returns information on the selected contact: bot and contact ID,
information from messenger, 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: getContactById
x-ai-role: crm_data_analyst
x-ai-description: >-
Retrieves a complete profile snapshot of a single bot contact —
including messenger metadata, tags, variables, and engagement history.
This is the primary lookup endpoint when you need to inspect or verify a
contact's current state before triggering personalized flows or
debugging delivery issues.
x-ai-reasoning-instructions:
- >-
Ensure the contact ID is valid and was obtained via a tag/variable
search or directly from the account UI — do not guess IDs.
- >-
Note that this endpoint returns bot-context data (messenger fields,
activity), not email subscriber data — use the appropriate address
book endpoints for email contacts.
- >-
If the goal is bulk lookup, consider whether a search-by-tag endpoint
would be more efficient than repeated single-contact calls.
x-ai-responding-instructions:
- >-
Highlight the contact's bot ID and messenger-side ID so the user can
correlate them across systems.
- >-
Surface any tags and variables present on the contact, as these are
typically what downstream automation logic depends on.
- >-
If the contact is not found or the ID is invalid, explain how to
obtain a valid contact ID (tag search, variable search, or account
UI).
x-ai-suggestions:
- >-
Use the returned tags and variables to decide which message flow or
segment this contact belongs to.
- >-
After inspecting the contact, consider `updateContactVariables` or
`addTagToContact` as follow-up actions.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/contacts/getByPhone:
get:
summary: Get contact info by phone number
description: >-
Returns information on the selected contact: bot and contact ID,
information from messenger, list of tags and variables, activity data
and date added
security:
- oAuth2ClientCredentials: []
tags:
- contacts
parameters:
- in: query
name: phone
required: true
schema:
type: string
description: Contact's phone number in international format.
- 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.
responses:
'200':
description: Operation successful
content:
application/json:
schema:
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Contact'
type: object
operationId: getContactByPhone
x-ai-role: chatbot_crm_specialist
x-ai-description: >-
Retrieves a full contact profile by phone number within a specific bot
context. This is the primary lookup method when you have a phone number
but not a contact ID — useful for deduplication, pre-flight checks
before sending messages, or enriching external CRM records with
SendPulse messenger data.
x-ai-reasoning-instructions:
- >-
Phone number must be in international format (e.g., +14155552671).
Validate or normalize the format before calling.
- >-
bot_id is mandatory — the same phone number may exist in multiple bots
as separate contacts. Always confirm which bot context is relevant.
- >-
Use this endpoint to check if a contact exists before attempting to
create or message them.
- >-
If the contact is not found, consider using the list contacts endpoint
to verify bot_id correctness before assuming the contact is absent.
x-ai-responding-instructions:
- >-
Surface the contact ID and bot ID from the response — these are
required for follow-up operations like sending messages or updating
variables.
- >-
Highlight any tags or variables returned, as they often reveal the
contact's segment or funnel stage.
- >-
If activity data is present, summarize recency to help the user assess
contact engagement.
- >-
If the call fails due to a missing contact, suggest verifying the
phone format or checking the correct bot_id.
x-ai-suggestions:
- >-
Use the returned contact ID with `sendMessage` to initiate a
conversation.
- >-
Check returned variables to determine if contact data needs updating
before outreach.
- >-
Cross-reference activity data with campaign timing to avoid messaging
inactive contacts.
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 based on a specific tag.
Tags in SendPulse chatbots act as behavioral or segmentation labels —
this endpoint is the primary way to build targeted audiences for
broadcasts or automations without exporting the full contact list.
x-ai-reasoning-instructions:
- >-
Confirm the bot_id is valid and accessible before querying — contacts
are bot-scoped and do not span across bots.
- >-
Tags are case-sensitive; advise the user to verify exact tag spelling
if results are unexpectedly empty.
- >-
Use `size` and `skip` for pagination when the contact base is large —
default limits may truncate results silently.
- >-
If the goal is a broadcast or automation, note that this endpoint is
read-only — the result must be fed into a separate send or segment
operation.
x-ai-responding-instructions:
- >-
Report the total number of contacts returned and clarify if pagination
was applied.
- >-
If the result is empty, suggest checking tag spelling or listing
available tags via a discovery endpoint.
- >-
When results are used for targeting, recommend confirming the segment
size before initiating a broadcast.
x-ai-suggestions:
- >-
Use `size=100&skip=0` as a starting pagination window for large
audiences.
- >-
Combine with a send-message endpoint to create a targeted campaign for
this tag segment.
- >-
Cross-reference with `getContactsByVariable` if tag-based filtering
returns insufficient granularity.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/contacts/getByVariable:
get:
summary: Get contacts by variable
description: >-
Returns 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 to search by; required parameter if you do not
pass variable_name and bot_id.
- in: query
name: variable_name
schema:
type: string
description: >-
Contact’s variable name to search by; required parameter and passed
with the bot_id parameter, if you do not pass variable_id.
- in: query
name: bot_id
schema:
type: string
description: >-
Bot ID; required parameter and passed with the variable_name
parameter, if you do not pass variable_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_analyst
x-ai-description: >-
Retrieves a filtered list of bot contacts based on a specific CRM
variable value. This is a targeted lookup mechanism — instead of
fetching all contacts, it allows precise segmentation by variable (e.g.,
'plan=premium', 'city=Kyiv'). Supports two resolution paths: by global
variable_id alone, or by variable_name scoped to a specific bot_id.
x-ai-reasoning-instructions:
- >-
Determine which lookup path to use: if variable_id is known, use it
alone; if only variable_name is known, require bot_id alongside it.
- >-
Never pass both variable_id and variable_name together — resolve the
ambiguity before calling.
- >-
Validate that variable_value is non-empty; an empty string will match
incorrectly or return no results.
- >-
Use size and skip parameters for large result sets to avoid
overwhelming downstream consumers.
- >-
If bot_id is needed but unknown, suggest fetching it via the
list-of-bots endpoint first.
x-ai-responding-instructions:
- Report how many contacts matched, not just whether the call succeeded.
- >-
If the result is empty, suggest verifying the variable_value casing or
checking if the variable exists for that bot.
- >-
If paginating, remind the user to increment skip by size to fetch the
next batch.
- >-
Surface contact IDs from the response as the primary next-step input
for further operations (e.g., sending a message).
x-ai-suggestions:
- >-
Use variable_id when available — it is bot-agnostic and more stable
than variable_name.
- Combine with pagination (size=50, skip=0) for large contact bases.
- >-
Typical variable_value examples: 'premium', 'true', 'ua',
'2024-cohort'.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/contacts/mark-read:
put:
summary: Mark messages as read
description: Mark contact all messages as read (set unread count 0)
security:
- oAuth2ClientCredentials: []
tags:
- contacts
parameters:
- in: query
name: contact_id
schema:
type: string
description: Contact’s ID for set unread count as 0
responses:
'200':
description: Operation successful
content:
application/json:
schema:
properties:
count:
type: integer
description: Contact messages count marked as read
type: object
operationId: markContactMessagesAsRead
x-ai-role: customer_support_specialist
x-ai-description: >-
Resets the unread message counter for a specific c
# --- truncated at 32 KB (222 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-whatsapp-openapi.yml