Instagram chatbots — bots, subscribers, variables, flows and campaigns, including comment-triggered flows and story mentions.
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:
fb_user:
type: object
properties:
id:
type: string
first_name:
type: string
last_name:
type: string
name:
type: string
name_format:
type: string
short_name:
type: string
picture:
type: object
properties:
data:
type: object
properties:
height:
type: integer
is_silhouette:
type: boolean
url:
type: string
width:
type: integer
ig_user:
type: object
properties:
id:
type: integer
ig_id:
type: integer
followers_count:
type:
- integer
- 'null'
follows_count:
type:
- integer
- 'null'
media_count:
type:
- integer
- 'null'
profile_picture_url:
type:
- string
- 'null'
username:
type: string
website:
type:
- string
- 'null'
ig_page:
type: object
properties:
instagram_business_account:
type: object
properties:
id:
type: integer
ig_id:
type: integer
name:
type: string
biography:
type:
- string
- 'null'
followers_count:
type:
- integer
- 'null'
follows_count:
type:
- integer
- 'null'
media_count:
type:
- integer
- 'null'
profile_picture_url:
type:
- string
- 'null'
website:
type:
- string
- 'null'
username:
type: string
id:
type: integer
category:
type: string
category_list:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
name:
type: string
picture:
type: object
properties:
data:
type: object
properties:
height:
type: integer
is_silhouette:
type: boolean
url:
type: string
width:
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:
id:
type: integer
user_name:
type:
- string
- 'null'
first_name:
type: string
last_name:
type:
- string
- 'null'
name:
type: string
profile_pic:
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
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` - 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 Instagram 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: Instagram 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 the full profile of a specific chatbot contact by their unique
ID. This is the primary lookup endpoint for resolving a contact ID into
structured data — including messenger metadata, tag/variable
assignments, and engagement history. Use it before personalizing
messages or making decisions based on contact state.
x-ai-reasoning-instructions:
- >-
Ensure you have a valid contact ID before calling — obtain it via
contact search by tag/variable or from the chat window URL in the
SendPulse account.
- >-
This endpoint returns a snapshot of the contact at call time; cache
results only for short-lived operations.
- >-
If the contact is not found, check whether the ID belongs to the
correct bot — IDs are bot-scoped.
x-ai-responding-instructions:
- >-
Surface the most actionable fields first: contact name, bot
association, active tags, and variables.
- >-
If the response includes activity data, summarize engagement recency
to help the user assess contact relevance.
- >-
If the contact has no tags or variables, suggest adding them via the
appropriate tag/variable assignment endpoints.
x-ai-suggestions:
- >-
Use the returned tag list to decide which campaign segment this
contact belongs to.
- >-
Check variable values before triggering a personalized flow to ensure
required data is present.
- >-
Follow up with a message-send endpoint if the contact is active and
reachable.
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 by a specific tag, enabling
segmented audience analysis and targeted follow-up workflows. Tags in
SendPulse chatbots act as behavioral or demographic labels assigned
during automation flows — querying by tag is the primary way to identify
cohorts for re-engagement or conditional branching logic.
x-ai-reasoning-instructions:
- >-
Before calling, confirm the bot_id is valid by cross-referencing with
the list of available bots if not already known.
- >-
Tags are case-sensitive — ask the user to confirm the exact tag string
if there is any ambiguity.
- >-
Use `size` and `skip` for pagination when the contact list may be
large; default page sizes vary, so explicitly set `size` for
predictable results.
- >-
If the result is empty, consider whether the tag was recently added or
if it applies to a different bot.
x-ai-responding-instructions:
- >-
Report the number of contacts returned and whether pagination was
applied.
- >-
If the list is empty, suggest verifying the tag spelling or checking
if contacts exist under a different bot.
- >-
Highlight key contact identifiers (e.g., IDs, names) to support
downstream actions like sending messages or updating tags.
- >-
If paginated results are likely incomplete, prompt the user to
increase `size` or iterate with `skip`.
x-ai-suggestions:
- >-
Use this endpoint to build re-engagement sequences for a specific
subscriber segment.
- >-
Combine with a broadcast endpoint to send targeted messages to all
contacts with this tag.
- >-
Iterate with skip=0, skip=100, skip=200... to collect all contacts
when the total exceeds the page size.
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: >-
Enables targeted contact lookup within a bot's audience based on a
custom variable value — useful for segmentation, personalization logic,
and pre-campaign filtering. In SendPulse chatbots, variables store
behavioral and profile data per contact; this endpoint acts as a dynamic
query interface over that data, allowing agents to find specific users
without iterating the full contact list.
x-ai-reasoning-instructions:
- >-
Determine whether `variable_id` or `variable_name` + `bot_id` pair is
available — prefer `variable_id` when known as it is unambiguous.
- >-
If only `variable_name` is provided, ensure `bot_id` is also supplied;
the combination is required to resolve the variable in scope.
- >-
Use `size` and `skip` for paginated retrieval — default batch sizes
may be small; iterate if the total result set is expected to be large.
- >-
Validate that `variable_value` matches the expected data type of the
variable (e.g., string, number) to avoid silent empty results.
- >-
Consider that variable names may not be unique across bots — always
scope lookups with `bot_id` unless `variable_id` is used.
x-ai-responding-instructions:
- >-
Report the number of contacts returned and whether pagination was
applied.
- >-
If the result is empty, suggest verifying the variable name/value
spelling or confirming the contact exists in the specified bot.
- >-
If multiple pages are available, recommend iterating with `skip` to
retrieve the full dataset.
- >-
Highlight any returned contact identifiers that can be used for
follow-up operations (e.g., sending a message, updating a variable).
x-ai-suggestions:
- >-
Use `variable_id` over `variable_name` when possible to avoid
cross-bot ambiguity.
- >-
Combine with `sendMessageToContact` to act on found contacts
immediately.
- >-
Use pagination (`size`/`skip`) when querying high-cardinality
variables like 'city' or 'plan'.
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
message:
text: string
Send a message with an image:
value:
contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
messages:
- type: image
message:
attachment:
type: image
payload:
is_external_attachment: true
url: https://example.com/image.png
Send a message with a carousel:
value:
contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
messages:
- type: generic_template
message:
attachment:
payload:
elements:
- title: Example title
subtitle: Example subtitle
image_url: https://example.com/image.png
is_external_attachment: true
buttons:
- type: web_url
title: Example button
url: https://example.com/
Send a message with url button:
value:
contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
messages:
- type: generic_template
message:
attachment:
payload:
elements:
- title: Example title
buttons:
- type: web_url
title: Example button
url: https://example.com/
Send a message with payload button:
value:
contact_id: xxxxxxxxxxxxxxxxxxxxxxxx
messages:
- type: generic_template
message:
attachment:
payload:
elements:
- title: Example title
buttons:
- type: postback
title: Example button
data:
to_chain_id: xxxxxxxxxxxxxxxxxxxxxxxx
responses:
'200':
description: Operation successful
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
operationId: sendMessageToContact
x-ai-role: chatbot_communication_specialist
x-ai-description: >-
Delivers a direct message to a specific contact identified by their
unique contact_id. This endpoint is the core of 1-to-1 outbound
messaging in chatbot flows — it bypasses broadcast campaigns and allows
real-time, personalized interaction. Supports rich media types: plain
text, images, and interactive carousels with CTA buttons (URL redirects
or postback triggers to flow chains). Use this when you need to
programmatically respond to user actions, send transactional
notifications, or initiate conversations outside of automated flows.
x-ai-reasoning-instructions:
- >-
Resolve the contact_id before calling: use contact search by tag or
variable if you only have user metadata. The ID can also be extracted
from the account UI URL of the chat window.
- >-
Select the message type based on intent: use 'text' for simple
replies, 'image' for visual content, 'generic_template' for
interactive carousels with buttons.
- >-
When using 'generic_template' with buttons, distinguish between
'web_url' (external link) and 'postback' (triggers a chain via
to_chain_id) — use postback when the goal is to continue a bot flow.
- >-
Ensure 'is_external_attachment: true' is set when referencing hosted
image URLs to avoid upload errors.
- >-
Validate that the contact is active and reachable on the target
channel before sending — unresolvable contacts will silently fail on
some integrations.
x-ai-responding-instructions:
-
# --- truncated at 32 KB (150 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-instagram-openapi.yml