TikTok chatbots — direct-message automation and comment-reply workflows for TikTok Business accounts.
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:
account:
type: object
properties:
display_name:
type: string
username:
type: string
profile_deep_link:
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: string
conversation_id:
type: string
display_name:
type: string
username:
type: string
profile_image:
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
- 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 TikTok 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: TikTok 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 messenger contact by their unique
ID. This is the primary lookup endpoint for resolving a contact ID
(obtained via tag/variable search) into actionable data: messenger
identity, tags, variables, activity history, and enrollment date.
Essential before personalizing outreach or auditing contact state.
x-ai-reasoning-instructions:
- >-
Ensure the contact ID is obtained beforehand — use tag or variable
search endpoints if only partial info is available.
- >-
Note that the ID is messenger-scoped: the same person may have
different contact IDs across bots.
- >-
If the response returns no data, verify the bot context — the contact
must belong to the bot associated with the current OAuth token.
- >-
Activity data can indicate whether the contact is still reachable
(e.g., blocked, unsubscribed).
x-ai-responding-instructions:
- >-
Present the contact's messenger identity and key variables in a
readable summary.
- Highlight any tags that indicate segmentation or funnel stage.
- >-
If activity data shows inactivity or opt-out, proactively flag this to
the user.
- >-
Suggest follow-up actions such as sending a message or updating a
variable if the context warrants it.
x-ai-suggestions:
- >-
Use this endpoint to verify contact state before triggering a bot
flow.
- >-
Combine with variable-update endpoints to enrich the contact profile
after retrieval.
- >-
Cross-reference tags with campaign logic to determine eligibility for
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_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
applied during automations or manually. This endpoint is the primary
mechanism for targeted audience extraction — enabling campaign
targeting, re-engagement flows, or data exports for a specific cohort
without pulling the entire contact list.
x-ai-reasoning-instructions:
- >-
Verify the bot_id is valid and belongs to the current account before
querying — an incorrect bot_id will return an empty result silently.
- >-
Tags are case-sensitive in SendPulse; confirm the exact tag value with
the user if results are unexpectedly empty.
- >-
When the user needs all contacts for a tag, implement pagination:
start with skip=0, then increment by the size value until the returned
array length is less than size.
- >-
If the user hasn't specified size, default to a reasonable batch
(e.g., 100) and mention that pagination may be needed for large
audiences.
- >-
Consider that a contact may have multiple tags — this endpoint returns
contacts where the tag is present, not where it is the only tag.
x-ai-responding-instructions:
- >-
Report the number of contacts returned and whether pagination was
applied.
- >-
If the result is empty, suggest verifying the tag spelling and that
the bot_id is correct.
- >-
When returning paginated results, clearly indicate the current batch
range (e.g., 'contacts 1–100 of an unknown total').
- >-
Suggest follow-up actions such as sending a broadcast to this segment
or exporting the contact list.
x-ai-suggestions:
- >-
Use this endpoint before triggering a targeted broadcast to validate
audience size.
- >-
Combine with tag management endpoints to build dynamic segmentation
workflows.
- >-
For full export, loop with skip increments equal to size until fewer
items than size are returned.
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_specialist
x-ai-description: >-
Performs a targeted lookup of bot contacts by matching a specific
variable value. This is the primary mechanism for identifying contacts
when you know a unique data point (e.g., an external user ID, email, or
order number stored as a variable) but not the internal SendPulse
contact ID. Essential for cross-system data sync and contact enrichment
workflows.
x-ai-reasoning-instructions:
- >-
Determine the lookup strategy: if you have a `variable_id`, use it
alone — it uniquely identifies the variable across all bots. If you
only have a variable name, you must also provide `bot_id`.
- >-
Validate that `variable_value` is always present — it is required
regardless of which identification strategy is used.
- >-
If the result set could be large, apply `size` and `skip` for
pagination to avoid incomplete responses.
- >-
If the user refers to a variable by name, check whether the bot ID is
available in context (e.g., from a prior 'list bots' call) before
proceeding.
- >-
Be aware that variable names are bot-scoped, so the same variable name
may exist in multiple bots with different IDs — always confirm the
target bot when using `variable_name`.
x-ai-responding-instructions:
- >-
Report the number of contacts returned and their key identifiers
(contact ID, name if available).
- >-
If the result is empty, suggest verifying the variable value or
checking that the correct bot was targeted.
- >-
If multiple contacts are returned for the same variable value,
highlight this as a data integrity consideration.
- >-
Suggest follow-up actions such as updating contact data or triggering
a flow for the matched contacts.
x-ai-suggestions:
- >-
Use `variable_id` when available — it is more reliable than variable
name resolution.
- To get `variable_id` or `bot_id`, call the 'list bots' endpoint first.
- >-
Typical use case: find a contact by their external CRM ID stored as a
custom variable.
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: Hello, World!
buttons:
- - text: click me
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_messaging_specialist
x-ai-description: >-
Sends a direct message (text, image, or file) to a specific contact
identified by their contact_id. This is the primary mechanism for
agent-initiated outbound communication within a chatbot conversation —
bypassing campaigns and targeting a single user with precision. Useful
for transactional notifications, support follow-ups, or triggered
responses based on CRM events.
x-ai-reasoning-instructions:
- >-
Ensure contact_id is valid and belongs to an active contact — use
contact search by tag or variable if the ID is unknown.
- >-
Verify the message type matches the content structure: 'text' requires
a 'text' object, files/images require their respective content types.
- >-
Buttons in a text message must reference valid chain IDs (to_chain_id)
— confirm they exist before sending.
- >-
Consider the contact's opt-in status and channel context before
initiating an unsolicited message.
- >-
If sending rich content (image/file), ensure the URL or file reference
is publicly accessible.
x-ai-responding-instructions:
- Confirm the message was delivered by reporting a successful response.
- >-
If the contact_id was resolved dynamically (e.g., via search), mention
which contact received the message.
- >-
On failure, clarify whether the issue is an invalid contact_id,
malformed message structure, or permission error.
- >-
Suggest a follow-up action if appropriate — e.g., waiting for a reply
event or logging the interaction in the CRM.
x-ai-suggestions:
- >-
Use contact search endpoints to resolve contact_id from a known email,
tag, or custom variable before calling this endpoint.
- >-
For multi-step flows, chain messages with button postbacks referencing
existing bot chain IDs.
- >-
Prefer structured messages with buttons over plain text when guiding
users through a decision flow.
x-ai-capabilities:
confirmation:
type: Recommended
message: >-
This will send a real-time message directly to the contact. Confirm
before proceeding if triggered by automated logic.
security_info:
data_handling:
- ExternalUserCommunication
- ResourceStateUpdate
/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
variable_value: string
Set by variable ID:
value:
contact_id: string
variables:
- variable_id: string
variable_value: string
- variable_id: string
variable_value: string
responses:
'200':
description: Operation successful
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
operationId: setContactVariable
x-ai-role: crm_data_specialist
x-ai-description: >-
Assigns or updates one or more variable values for a specific contact in
a chatbot channel. Variables are the primary mechanism for personalizing
automated flows and segmenting audiences — setting them correctly is a
prerequisite for conditional logic, dynamic message rendering, and
targeted broadcasts.
x-ai-reasoning-instructions:
- >-
Resolve the contact_id first — it is not a human-readable identifier;
use contact search by tag or variable if you only know the user's name
or phone number.
- >-
Prefer variable_name over variable_id when the variable name is known
— it is more readable and less error-prone.
- >-
Use variable_id when the name is ambiguous or when operating in a
multi-language environment where variable names may differ.
- >-
Multiple variables can be set in a single call — batch them to avoid
redundant API requests.
- >-
Ensure variable_value type matches the variable's declared type in the
account (string, number, boolean) to preven
# --- truncated at 32 KB (139 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-tiktok-openapi.yml