Chatbots embedded in the SendPulse live chat website widget — bots, subscribers, variables, flows and campaigns.
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: string
- type: integer
type: object
Account:
properties:
tariff:
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
name:
type: string
avatar:
type:
- string
- 'null'
example: null
variables:
type: array
items:
type: object
settings:
type: object
properties:
service_links:
type: boolean
open_chat_notification:
type: boolean
disable_trigger_hints:
type: boolean
standard_text_settings:
type: object
widget:
type: object
properties:
sp_site:
type:
- string
- 'null'
example: null
website_url:
type: string
website_scheme:
type: string
website_domain:
type: string
title:
type: string
position:
type: string
color:
type: string
terms:
type:
- object
- 'null'
example: null
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
online:
type: boolean
channel_data:
type: object
properties:
id:
type: integer
full_name:
type: string
url:
type:
- string
- 'null'
example: null
lang:
type:
- string
- 'null'
example: 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
keywords_search_type:
type: integer
enum:
- 1
- 2
description: |2-
* `1` - STRICT_MATCH
* `2` - CONTAINS
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
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:
type:
- object
- 'null'
example: null
chain:
type:
- object
- 'null'
example: null
reject_reason:
type:
- string
- 'null'
example: null
data:
type: object
description: https://core.telegram.org/bots/api#message
example:
type: type
text: hello
subscriber_id: d86e2ca7-0000-0000-1111-1f1f32d0f0b1
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
type:
type: string
enum:
- text
- image
- document
description: |2-
* `1` - new
* `2` - sent
* `3` - delivered
* `4` - opened
* `5` - redirected
* `6` - rejected
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 LiveChat 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: LiveChat service API
version: 0.0.1
openapi: 3.1.2
paths:
/account:
get:
summary: Get account info
description: >-
Returns information about your current account pricing plan, the number
of messages in your plan, bots, contacts, list of tags, and variables
security:
- oAuth2ClientCredentials: []
tags:
- account
responses:
'200':
description: Operation successful
content:
application/json:
schema:
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Account'
type: object
operationId: getAccount
x-ai-role: account_management_specialist
x-ai-description: >-
Provides a comprehensive snapshot of the current account state,
including the active pricing plan, remaining message quotas, connected
bots, contact counts, and defined tags/variables. Use this as the entry
point for any workflow that depends on account capacity or configuration
— for example, before launching a campaign, verify that sufficient
message quota exists.
x-ai-reasoning-instructions:
- >-
Call this endpoint at the start of a session to establish baseline
account limits before executing quota-sensitive operations.
- >-
Use the pricing plan information to determine which features and API
endpoints are available to the user.
- >-
Cross-reference message quota against planned campaign volume to
proactively warn about potential limit breaches.
- >-
Use the tags and variables list to validate inputs in subsequent
contact or campaign operations.
x-ai-responding-instructions:
- >-
Summarize the active plan name and remaining message quota in a
human-readable way (e.g., '4 200 of 10 000 emails remaining').
- >-
If quota is below 20%, proactively suggest the user review their plan
or schedule sends accordingly.
- >-
Present the list of tags and variables as useful context for building
segments or personalized campaigns.
- >-
If the response indicates no bots or contacts, suggest onboarding
steps as logical next actions.
x-ai-suggestions:
- Use before `sendEmailCampaign` to verify sufficient quota.
- Use to list available tags before creating a new contact segment.
- Use to confirm bot count limits before adding a new chatbot.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/bots:
get:
summary: Get a list of connected bots
description: >-
Returns lists of bots with information about each: bot ID, channel
information, number of received and unread messages, bot status, and
creation date
security:
- oAuth2ClientCredentials: []
tags:
- bots
parameters:
- 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/Bot'
type: object
operationId: getBots
x-ai-role: chatbot_operations_manager
x-ai-description: >-
Provides a paginated inventory of all bots connected to the account.
Each bot entry exposes its channel affiliation, messaging activity
metrics (received vs. unread), operational status, and creation
timestamp — enabling at-a-glance fleet health assessment and channel
coverage audits.
x-ai-reasoning-instructions:
- >-
Use `skip` and `size` together to paginate through large bot fleets;
default to small page sizes to avoid payload bloat.
- >-
Check `status` field in each bot to identify inactive or misconfigured
bots before initiating campaigns.
- >-
Cross-reference unread message counts to detect bots that may require
attention or human handoff.
- >-
If the goal is to send a broadcast, use the returned bot IDs to target
specific channels downstream.
x-ai-responding-instructions:
- >-
Summarize the total number of bots returned and highlight any that are
inactive or have high unread counts.
- >-
If the list is empty, suggest that the user connect a bot via the
SendPulse dashboard first.
- >-
When presenting results, group by channel type (Telegram, WhatsApp,
etc.) for clarity.
- >-
Suggest using a specific bot ID in follow-up operations such as
sending messages or retrieving contacts.
x-ai-suggestions:
- Start with `size=10, skip=0` and paginate if more bots are expected.
- >-
Use this endpoint to discover available bot IDs before calling send or
contact management endpoints.
- Filter results client-side by `status` to work only with active bots.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/bots/statistics:
get:
summary: Get general statistics info by bot
description: Returns general statistics info by bot
security:
- oAuth2ClientCredentials: []
parameters:
- in: query
name: bot_id
required: true
schema:
type: string
description: >-
The 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.
tags:
- bots
responses:
'200':
description: Operation successful
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
subscribed_total_count:
type: integer
subscribed_active_count:
type: integer
outgoing_messages_total_count:
type: integer
operationId: getBotStatistics
x-ai-role: chatbot_analytics_specialist
x-ai-description: >-
Provides a high-level health snapshot of a specific bot: total
subscriber base, currently active subscribers, and total outgoing
message volume. Use this as the first diagnostic step before analyzing
campaign performance or troubleshooting engagement drops — it reveals
whether the bot is growing, stagnating, or losing audience.
x-ai-reasoning-instructions:
- >-
Ensure the bot_id is valid by cross-referencing with the list of bots
if not explicitly provided by the user.
- >-
Distinguish between subscribed_total_count and subscribed_active_count
— a large gap indicates significant churn or inactive subscribers
worth investigating.
- >-
If outgoing_messages_total_count is zero or very low relative to
subscriber count, suggest checking if any flows or broadcasts have
been launched.
x-ai-responding-instructions:
- >-
Present the three metrics together as a coherent snapshot, not just
raw numbers — e.g., 'The bot has 1,200 total subscribers, of which 870
are active, and has sent 4,500 messages in total.'
- >-
If active count is significantly lower than total, proactively note
that re-engagement campaigns or flow audits may be warranted.
- >-
Suggest next steps such as viewing specific flow performance or
launching a broadcast to re-engage inactive subscribers.
x-ai-suggestions:
- >-
Use this endpoint to monitor bot health on a regular cadence (e.g.,
weekly).
- >-
Combine with flow-level stats to identify which automations drive the
most engagement.
- >-
Compare subscribed_active_count trends over time to evaluate list
quality.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/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: getContact
x-ai-role: crm_data_analyst
x-ai-description: >-
Retrieves the full profile of a single chatbot contact by their unique
ID. This is the primary entry point for reading contact-level data —
including messenger metadata, custom variables, tags, and engagement
history — before performing any targeted action such as sending a
message, updating a variable, or segmenting the contact.
x-ai-reasoning-instructions:
- >-
Ensure you have a valid contact ID before calling this endpoint — IDs
can be retrieved via tag/variable search or from the account UI chat
URL.
- >-
Use this endpoint to verify contact existence and current state before
triggering follow-up actions (e.g., sending a message or updating
variables).
- >-
Check the returned `tags` and `variables` fields to determine if the
contact is already segmented or enriched before adding duplicates.
- >-
If the contact ID comes from user input, validate that it is a
non-empty string — the API treats ID as a string, not an integer.
x-ai-responding-instructions:
- >-
Summarize the contact's key identifiers (bot ID, contact ID) and
messenger-sourced info (name, username, channel) for the user.
- >-
Highlight any tags or variables attached to the contact, as these are
typically relevant to the user's next action.
- >-
If the contact was recently added or has low activity, mention this as
it may indicate a cold or unverified lead.
- >-
If the request fails (e.g., contact not found), suggest verifying the
ID via a contact search endpoint.
x-ai-suggestions:
- >-
After retrieving contact info, use `sendMessageToContact` to initiate
or continue a conversation.
- >-
Use the returned variable list to decide whether to call
`setContactVariable` for enrichment.
- >-
Cross-reference returned tags with campaign segments before adding the
contact to a flow.
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_manager
x-ai-description: >-
Retrieves a filtered slice of the bot's contact base using a tag label.
Tags in SendPulse chatbots act as behavioral or segmentation markers
assigned during flows or manually. This endpoint is the primary tool for
targeted segment extraction — essential before sending tag-specific
broadcasts, auditing segment health, or building conditional automation
logic.
x-ai-reasoning-instructions:
- >-
Require both `bot_id` and `tag` before calling — neither has a default
and both are mandatory.
- >-
If the user hasn't specified `size`, suggest a reasonable default
(e.g., 100) to avoid unbounded responses on large contact bases.
- >-
When paginating, track the total returned count against `size` — if
the result is smaller than `size`, the last page has been reached.
- >-
If the result is empty, suggest verifying the tag name for exact
case/spelling match, as tags are case-sensitive in SendPulse.
x-ai-responding-instructions:
- >-
Report how many contacts were returned and, if paginated, indicate
whether more pages likely exist.
- >-
If the list is large, recommend iterating with `skip` increments equal
to `size` to retrieve all contacts.
- >-
Suggest a logical next action based on context — e.g., sending a
broadcast to this segment or exporting the list.
x-ai-suggestions:
- >-
Use `size: 100` and `skip: 0` as a safe starting point for paginated
retrieval.
- >-
Follow up with a tag-targeted broadcast using the collected contact
IDs.
- >-
Combine with `getContactsByVariable` to cross-filter segments by both
tag and variable value.
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: >-
Performs a targeted lookup of chatbot contacts by matching a custom
variable value. This is the primary tool for cross-referencing your
external CRM data (e.g., user_id, order_id, phone) with SendPulse
chatbot contacts — useful for personalised outreach, deduplication, or
triggering flows for a specific audience segment.
x-ai-reasoning-instructions:
- >-
Determine which lookup strategy to use: if you have a variable_id, use
it alone (most precise); if you only have a variable name, you must
also provide bot_id.
- >-
Always require variable_value — it is the only mandatory parameter;
without it the query has no filter.
- >-
Use size and skip for pagination when you expect multiple matches
(e.g., shared variable values like a city or plan tier).
- >-
If the user provides a bot name instead of bot_id, first call the
list-bots endpoint to resolve the ID.
- >-
Be aware that variable_id is global, while variable_name
# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-live-chat-openapi.yml