Viber chatbots — bots, subscribers, variables, flows and campaigns with rich media, buttons and carousels.
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:
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
channel_data:
type: object
properties:
vb_account_info:
type: object
properties:
id:
type: string
name:
type: string
uri:
type: string
icon:
type: string
background:
type:
- string
- 'null'
category:
type: string
subcategory:
type: string
location:
type: object
properties:
lon:
type:
- float
- 'null'
lat:
type:
- float
- 'null'
country:
type: string
webhook:
type:
- string
- 'null'
event_types:
type:
- array
- 'null'
items:
type: string
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:
id:
type: integer
name:
type:
- string
- 'null'
avatar:
type:
- string
- 'null'
country:
type: string
language:
type: string
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
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
- 2
- 3
- 4
- 5
- 6
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 Viber 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: Viber 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 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 a complete profile snapshot of a single chatbot contact by
their ID. This is the primary lookup endpoint for resolving a known
contact ID into full profile data — including messenger metadata, tags,
variables, and engagement history. Typically used after a search or list
operation to hydrate a contact record before personalization or
segmentation logic.
x-ai-reasoning-instructions:
- >-
Ensure the contact ID was obtained from a prior search (by tag,
variable, or account UI) — it is not the same as a messenger user ID.
- >-
If the contact is not found, consider whether the ID belongs to a
different bot or has been deleted.
- >-
Use the returned tags and variables to inform downstream
personalization or segmentation decisions.
x-ai-responding-instructions:
- >-
Present the contact's key identifiers (bot ID, contact ID) and
messenger-sourced profile fields clearly.
- >-
Highlight any tags and variables attached to the contact as they are
often actionable.
- >-
If activity data is present, summarize last interaction date to give
context on contact freshness.
x-ai-suggestions:
- >-
Use the returned variable values to trigger conditional campaign
logic.
- >-
Cross-reference tags with segment definitions to determine campaign
eligibility.
- >-
Follow up with a send-message or variable-update operation if the
contact profile needs enrichment.
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 shared tag label.
Tags in SendPulse chatbots act as behavioral or segmentation markers
applied during flows or manually — querying by tag is the primary
mechanism for targeted audience selection before broadcasting or
triggering follow-up sequences.
x-ai-reasoning-instructions:
- >-
Confirm the bot_id is valid and belongs to the user's account before
querying — an incorrect bot_id silently returns an empty result.
- >-
Tags are case-sensitive; if results are unexpectedly empty, suggest
verifying the exact tag string used during contact tagging.
- >-
Use `size` and `skip` for large audiences — default limits may
truncate results without warning.
- >-
If the user wants to act on the returned contacts (e.g., send a
message), note that this endpoint is read-only and a separate
broadcast or flow trigger is required.
x-ai-responding-instructions:
- >-
Report the number of contacts returned and whether pagination was
applied.
- >-
If the result is empty, suggest checking tag spelling or using a
contact listing endpoint to inspect available tags.
- >-
If results are paginated, remind the user to increment `skip` to
retrieve subsequent batches.
- >-
Suggest follow-up actions such as sending a campaign to the returned
segment.
x-ai-suggestions:
- >-
Use tag values like 'vip', 'inactive_30d', or 'webinar_registered' for
precise segmentation.
- Combine with a broadcast endpoint to message the returned contacts.
- >-
Start with `size=50` and `skip=0` for the first page, then increment
`skip` by 50 for subsequent pages.
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 reverse lookup of chatbot contacts using custom variable
data. Useful when you know a business-specific identifier (e.g.,
user_id, email, order_id stored as a bot variable) and need to retrieve
the corresponding SendPulse contact record. This is a key bridge between
external CRM/business data and the chatbot subscriber base.
x-ai-reasoning-instructions:
- >-
Determine whether the caller has a variable_id or only a
variable_name+bot_id pair — these are mutually exclusive lookup paths;
clarify before calling.
- >-
variable_value is always required regardless of which identifier path
is used — ensure it is provided.
- >-
If the result set may be large, advise using size+skip pagination to
avoid overloading the response.
- >-
bot_id can be retrieved via the 'get list of bots' endpoint if the
caller does not have it; suggest this if bot_id is missing.
- >-
Variable names are bot-scoped — the same variable_name may exist
across multiple bots with different meanings; always pair
variable_name with the correct bot_id.
x-ai-responding-instructions:
- >-
Report how many contacts matched the query and list their key
identifiers (contact id, name).
- >-
If the result is empty, suggest verifying the variable_value spelling
and confirm the variable exists for the target bot.
- >-
If pagination was used, indicate whether more records may exist beyond
the current batch and suggest incrementing skip.
- >-
Suggest follow-up actions such as sending a message or updating the
contact's variables based on the retrieved contact list.
x-ai-suggestions:
- >-
Use variable_id when you have it — it is bot-agnostic and more precise
than variable_name+bot_id.
- >-
Typical variable_name values: 'email', 'phone', 'external_user_id',
'order_id'.
- >-
Start with size=10 for exploratory lookups; increase for bulk
resolution tasks.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/contacts/send:
post:
summary: Send a message to a contact
description: >-
Sends a text message, image, or a file to the contact with the specified
contact ID. To view an example of the request body, select a message
type from the drop-down list
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.
messages:
type: array
description: >-
Message to send, specifying the type and content of the
campaign
items:
type: object
description: >-
Message to send, specifying the type and content of the
campaign
required:
- contact_id
- message
examples:
Send a text message:
value:
contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
messages:
- type: text
text:
text: string
buttons:
- - text: Example url button
type: web_url
url: https://example.com/
- - text: Example postback button
type: postback
to_chain_id: xxxxxxxxxxxxxxxxxxxxxxxx
Send a message with an image:
value:
contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
messages:
- type: image
image:
file:
is_path_absolute: true
path: https://example.com/image.png
Send a message with a carousel:
value:
contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
messages:
- type: generic_template
generic_template:
- title: Example title
subtitle: Example subtitle
image:
is_path_absolute: true
path: https://example.com/image.png
buttons:
- - type: web_url
text: Example button
url: https://example.com/
- text: Example postback button
type: postback
to_chain_id: xxxxxxxxxxxxxxxxxxxxxxxx
responses:
'200':
description: Operation successful
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
operationId: sendContactMessage
x-ai-role: conversational_marketing_specialist
x-ai-description: >-
Initiates a direct outbound message to a specific chatbot contact.
Unlike broadcast campaigns, this endpoint targets a single identified
contact by ID, enabling personalized, event-driven or support-driven
communication. Supports rich message types — text with interactive
buttons, images, and carousels — making it the primary tool for
agent-assisted or automated 1:1 engagement flows.
x-ai-reasoning-instructions:
- >-
Obtain `contact_id` first via contact search by tag or variable if not
already known — it is a mandatory prerequisite.
- >-
Choose the message type (`text`, `image`, `generic_template`) based on
the communication goal: text for quick replies, image for visual
content, generic_template for interactive carousels with CTAs.
- >-
When using `postback` buttons, ensure `to_chain_id` references a valid
automation chain to avoid broken flows.
- >-
For `web_url` buttons, validate that the URL is publicly accessible
and uses HTTPS.
- >-
Be aware that this sends the message immediately — there is no
scheduling or draft state.
x-ai-responding-instructions:
- >-
Confirm that the message was dispatched successfully, mentioning the
contact ID it was sent to.
- >-
If the message included interactive buttons, note that the contact's
response will trigger the linked chain or postback handler.
- >-
In case of failure, check whether the contact ID is valid and whether
the contact has an active session or subscription.
- >-
Suggest follow-up actions such as tracking contact engagement or
triggering a follow-up message via automation.
x-ai-suggestions:
- >-
Use `text` type with `buttons` to guide the contact through a decision
tree.
- >-
Use `generic_template` for product showcases, onboarding steps, or
multi-option menus.
- >-
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. This action
is immediate and cannot be recalled.
security_info:
data_handling:
- ExternalCommunicationTriggered
- UserFacingAction
/contacts/setVariable:
post:
summary: Assign a variable to contact
description: Adds or updates the value of a variable for the selected contact.
security:
- oAuth2ClientCredentials: []
tags:
- contacts
requestBody:
description: Choose one of available request body
required: true
content:
application/json:
schema:
type: object
required:
- contact_id
- variables
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.
variables:
type: array
description: api.paths.contacts.setVariable.parameters.variables
items:
oneOf:
- type: object
required:
- variable_name
- variable_value
properties:
variable_name:
type: string
description: Name of the variable
variable_value:
description: The value that is set for the variable
anyOf:
- type: string
- type: number
- type: boolean
- type: object
required:
- variable_id
- variable_value
properties:
variable_id:
type: string
description: >-
The ID of the created variable can be obtained via
other methods
variable_value:
description: The value that is set for the variable
anyOf:
- type: string
- type: number
- type: boolean
examples:
Set by variable name:
value:
contact_id: string
variables:
- variable_name: string
variable_value: string
- variable_name: string
# --- truncated at 32 KB (143 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-viber-chatbot-openapi.yml