Telegram chatbots — bots, subscribers, variables, flows, campaigns, chats, inline keyboards and custom commands.
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:
id:
type: integer
name:
type: string
username:
type: string
inbox:
type: object
properties:
total:
type: integer
unread:
type: integer
commands_menu:
type: object
properties:
status:
type: integer
enum:
- 1
- 2
description: |2-
* `1` - active
* `2` - inactive
commands:
type: array
items:
type: object
properties:
description:
type:
- string
- 'null'
command:
type: string
flow_id:
type: string
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
telegram_id:
type: string
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
example: 1
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
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
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
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:
- 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
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:
- 1
- 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
created_at:
type: string
example: 2020-12-11T21:00:00.000Z
sent_by:
type:
- object
- 'null'
description: Operator data, which send a message
type:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
description: |-
Internal type of message
* `1` - 'Internal chat',
* `2` - 'External chat',
* `3` - 'Payment',
* `4` - 'Campaign',
* `5` - 'Operator',
* `6` - 'Operator note',
* `7` - 'Feed comment',
channel:
type: string
enum:
- ma
- ma_chat
- api
- rss
- echo
- jivo
- open_ai
- payment
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 Telegram 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: Telegram 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 single chatbot contact by their unique
ID. This is the primary lookup endpoint for resolving a contact ID into
a rich profile — including messenger metadata, segmentation tags, custom
variables, and engagement history. Typically used before performing
personalised actions (sending messages, updating variables) or after a
search that returned only an ID.
x-ai-reasoning-instructions:
- >-
Ensure the contact ID is obtained from a prior search (by tag,
variable, or from the account UI URL) — it is not guessable.
- >-
If the caller does not have a contact ID yet, suggest using a
contact-search endpoint first.
- >-
Check whether the returned data includes the fields the user needs
(tags, variables, activity) before deciding on follow-up actions.
- >-
Be aware that contact IDs are bot-scoped; a contact ID from one bot
will not resolve correctly for another bot.
x-ai-responding-instructions:
- >-
Summarise the contact's key identity fields (bot ID, contact ID,
messenger handle) first.
- >-
Highlight any tags and variables present, as these are most commonly
needed for segmentation or personalisation tasks.
- >-
If the activity data shows no recent engagement, flag this to the user
as it may affect campaign deliverability decisions.
- >-
If the contact is not found, explain that the ID may belong to a
different bot or may have been deleted.
x-ai-suggestions:
- >-
Use the returned contact ID with `sendMessageToContact` to initiate a
personalised message.
- >-
Inspect the `variables` array to decide whether custom data needs to
be updated via an update-variable endpoint.
- >-
Cross-reference tags with campaign segment rules to verify correct
audience inclusion.
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 tag, enabling
segment-level analysis and targeting. Tags in SendPulse chatbots serve
as lightweight segmentation labels — this endpoint is the primary way to
enumerate a tagged audience before triggering automations, exports, or
bulk messaging flows.
x-ai-reasoning-instructions:
- >-
Ensure the bot_id belongs to the correct bot — the same tag may exist
across multiple bots with different audiences.
- >-
Use size/skip parameters for large contact bases to avoid response
timeouts; default page size is typically small.
- >-
If the result is empty, clarify whether the tag exists at all or
simply has no contacts assigned — consider calling a tag-listing
endpoint first.
- >-
Tags are case-sensitive in most implementations; confirm the exact tag
string with the user before querying.
x-ai-responding-instructions:
- >-
Report the total number of contacts returned and whether pagination
was applied.
- >-
If the list is partial (size limit reached), prompt the user to
paginate using the skip parameter.
- >-
Suggest follow-up actions such as sending a broadcast or exporting
contacts from this segment.
- >-
If the result is empty, propose verifying the tag name or checking if
contacts were tagged correctly.
x-ai-suggestions:
- >-
Use this endpoint before a targeted broadcast to preview the audience
size.
- >-
Combine with `skip` and `size` to iterate over large tagged segments
in batches.
- >-
Cross-reference with bot subscriber lists to verify tag assignment
accuracy.
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 bot contacts based on a custom variable
value. This is essentially a CRM query tool — instead of browsing
contacts manually, it lets agents find specific users who have a
particular value stored in a variable (e.g., all contacts where
`plan=premium` or `order_id=12345`). Useful for triggering follow-up
flows, auditing segmentation, or verifying that variable assignment
worked correctly.
x-ai-reasoning-instructions:
- >-
Determine whether the caller has a variable_id available — if yes, use
it directly; if not, require both variable_name and bot_id together.
- >-
Ensure variable_value is always provided; without it the request will
fail regardless of which identifier is used.
- >-
If the expected result set may be large, advise using size and skip
for paginated retrieval to avoid performance issues.
- >-
Confirm the bot_id is from the correct bot — variables with the same
name can exist across multiple bots and return different contacts.
x-ai-responding-instructions:
- >-
Report how many contacts matched and list key identifiers (contact
IDs, names if available) from the response.
- >-
If the result is empty, suggest verifying the variable_value spelling
or checking whether the variable is actually assigned to contacts in
that bot.
- >-
If pagination was used, indicate whether more results may exist and
suggest incrementing skip to fetch the next batch.
- >-
Do not expose full contact data unless the user explicitly requests it
— summarise instead.
x-ai-suggestions:
- >-
Use variable_id when you already have it from a previous variable
listing call — it is more reliable than name-based lookup.
- >-
Combine with `getBots` to resolve bot_id before calling this endpoint
if only a bot name is known.
- >-
After retrieving contacts, consider using their IDs to send targeted
messages or update variables via bot contact endpoints.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
- PII — response contains contact profile data
/contacts/getByTelegramId:
get:
summary: Get contact by Telegram ID
description: Returns a bot contact by Telegram ID.
security:
- oAuth2ClientCredentials: []
tags:
- contacts
parameters:
- in: query
name: bot_id
required: true
schema:
type: string
description: Bot identifier
- in: query
name: telegram_id
required: true
schema:
type: integer
description: Telegram ID of the user or chat
- in: query
name: business_connection_id
required: false
schema:
type:
- string
- 'null'
description: Telegram business connection identifier (optional)
responses:
'200':
description: Contact successfully found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Contact'
operationId: getContactByTelegramId
x-ai-role: telegram_bot_integration_specialist
x-ai-description: >-
Retrieves a specific bot contact by their Telegram ID. This is the
primary lookup mechanism when you know the user's Telegram identity but
not the internal SendPulse contact ID — common in webhook handlers after
receiving a Telegram update, or when syncing external CRM data with bot
subscriber records.
x-ai-reasoning-instructions:
- >-
Ensure bot_id belongs to an active Telegram bot in the account before
querying.
- >-
telegram_id refers to Telegram's internal user/chat identifier — it is
not a username or phone number.
- >-
If business_connection_id is provided, the lookup scope narrows to
that specific business connection; omit it for standard bot contacts.
- >-
If the contact is not found (non-200 or empty data), consider whether
the user has ever interacted with the bot — contacts are created only
after the first interaction.
x-ai-responding-instructions:
- >-
Confirm which bot the contact was found in by echoing the bot_id
context.
- >-
If the contact is found, highlight key identifiable fields (e.g.,
name, telegram_id) from the returned Contact object.
- >-
If no contact is returned, explain that the user may not have started
the bot yet or the telegram_id may be incorrect.
- >-
Suggest follow-up actions such as sending a message or updating
contact variables.
x-ai-suggestions:
- >-
Use this endpoint in Telegram webhook handlers to resolve incoming
user messages to SendPulse contacts.
- >-
Combine with sendMessage endpoints to immediately act on the retrieved
contact.
- >-
Pass business_connection_id only when operating in Telegram Business
mode.
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 contact to zero,
signaling that all messages in the conversation have been reviewed. This
is a UI/state sync operation — it does not delete or alter messages,
only updates the read status used for badge counts and inbox
prioritization.
x-ai-reasoning-instructions:
- >-
Confirm the contact_id exists before calling; an invalid ID will
silently fail or return 0.
- >-
Use this after fetching and displaying messages to keep inbox state
consistent.
- >-
This affects only the unread counter — do not use it as a substitute
for actual message acknowledgement in workflows.
x-ai-responding-instructions:
- Report the number of messages marked as read from the `count` field.
- >-
If count is 0, clarify that the contact had no unread messages — the
operation was a no-op.
- >-
Suggest following up with a contact list refresh to reflect the
updated state in the UI.
x-ai-suggestions:
- Call after rendering a conversation thread to sync read state.
- >-
Combine with `getContactMessages` to fetch and immediately mark as
read in one flow.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ResourceStateUpdate
/contacts/mark-unread:
put:
summary: Mark a chat with the contact as unread
description: Marks the last message of a specific contact as unread.
security:
- oAuth2ClientCredentials: []
tags:
- contacts
parameters:
- in: query
name: contact_id
schema:
type: string
description: The ID of the contact whose last message will be marked as unread.
responses:
'200':
description: The number of messages successfully marked as unread.
content:
application/json:
schema:
properties:
count:
type: integer
example: 1
description: api.paths.contacts.mark-unread.responses.properties.count
type: object
operationId: markContactUnread
x-ai-role: customer_support_specialist
x-ai-description: >-
Flags the last message of a contact's chat as unread, signaling to
support agents that this conversation requires attention. This is a
workflow management tool — it does not alter message content, only the
read/unread state used to drive operator queues and notification badges.
x-ai-reasoning-instructions:
- >-
Confirm that `contact_id` refers to an existing contact before calling
— an invalid ID will silently fail or return count: 0.
- >-
Use this endpoint when an operator needs to re-queue a conversation
for follow-up without sending a new message.
- >-
Be aware this marks only the *last* message as unread, not the entire
conversation history.
x-ai-responding-instructions:
- >-
Report the returned `count` value to confirm how many messages were
affected (expected: 1).
- >-
If `count` is 0, warn the user that no message was marked — likely due
to an invalid or already-unread contact.
- >-
Suggest checking the contact's chat via the inbox view to verify the
unread flag is visible.
# --- truncated at 32 KB (167 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-telegram-openapi.yml