TikTok
List TikTok conversations
List TikTok conversations (tickets) on one of the project's TikTok accounts, with optional filtering by assignment and status. Results are paginated and the response includes a meta block with counts for each assignment bucket (all, mine, unassigned, assigned) so you can render conversation tabs. This is the generic conversation listing endpoint — use the POST /filter variant for structured filters or the by-contact endpoint to scope to a single contact.
curl --request GET \
--url 'https://api.nabrah.ai/api/ext/omni_v2/tiktok' \
--header 'X-API-Key: <your-api-key>'{
"meta": {
"all_count": 0,
"mine_count": 0,
"unassigned_count": 0,
"assigned_count": 0
},
"payload": [
{
"account_id": 0,
"additional_attributes": {},
"agent_last_seen_at": 0,
"assignee_last_seen_at": 0,
"can_reply": false,
"contact_last_seen_at": 0,
"created_at": 0,
"custom_attributes": {},
"first_reply_created_at": 0,
"id": 0,
"inbox_id": 0,
"labels": [
"string"
],
"last_activity_at": 0,
"last_non_activity_message": {
"account_id": 0,
"additional_attributes": {},
"content": "string",
"content_attributes": {},
"content_type": "string",
"conversation": null,
"conversation_id": 0,
"created_at": 0,
"external_source_ids": {},
"id": 0,
"inbox_id": 0,
"message_type": 0,
"private": false,
"processed_message_content": "string",
"sender": null,
"sender_id": 0,
"sender_type": "string",
"sentiment": {},
"source_id": "string",
"status": "string",
"updated_at": "string",
"attachments": []
},
"messages": [
{
"account_id": null,
"additional_attributes": null,
"content": null,
"content_attributes": null,
"content_type": null,
"conversation": null,
"conversation_id": null,
"created_at": null,
"external_source_ids": null,
"id": null,
"inbox_id": null,
"message_type": null,
"private": null,
"processed_message_content": null,
"sender": null,
"sender_id": null,
"sender_type": null,
"sentiment": null,
"source_id": null,
"status": null,
"updated_at": null,
"attachments": null
}
],
"meta": {
"channel": "string",
"hmac_verified": false,
"sender": null,
"assignee": null
},
"muted": false,
"priority": "string",
"sla_policy_id": 0,
"snoozed_until": 0,
"status": "string",
"timestamp": 0,
"unread_count": 0,
"updated_at": 0
}
]
}Pagination & counts
The endpoint returns one page of conversations at a time inside payload, plus aggregate meta counts.
pagePass ?page=1 for the first page and increment to walk subsequent pages. When a page returns fewer items than the page size (or an empty payload), you have reached the end.
meta.all_count, meta.mine_count, meta.unassigned_count, and meta.assigned_count reflect the totals for each assignment bucket and are independent of the current page.
all_countmine_countunassigned_countassigned_countReading conversations
Each item in payload is a conversation. Useful fields: id (the conversation/ticket id), inbox_id (which TikTok account it belongs to), status, unread_count, and last_non_activity_message (the most recent real message).
Authenticate every request with the X-API-Key header. The key is scoped to a single project, so no project_id is required.
Choosing the TikTok account
A project can connect more than one TikTok account. inbox_id selects the account this call works on.
inbox_id is optional; the project's only TikTok account is used.
inbox_id is required and the call returns 400 without it. An id that is not one of the project's TikTok accounts returns 404.
inbox_idList the accounts and their ids with GET /api/ext/omni_v2/tiktok/inboxes.
Reply window
TikTok allows replies within 48 hours of the customer's last message; after that, nothing can be sent until the customer writes again. TikTok also limits how many messages you can send before the customer replies.
reply_window_ends_atEach TikTok conversation carries reply_window_ends_at: a Unix timestamp for when the reply window closes, counted from the customer's last message. Sending after it returns 409 reply_window_closed.
reply_window_ends_atAuthorization
X-API-KeystringheaderrequiredYour workspace API key. Create one in the dashboard under API keys.
Query parameters
assignee_typeenum(all | me | unassigned | assigned)Filter conversations by assignment relative to the API key's identity.
One of all, me, unassigned, or assigned. Defaults to all when omitted.
status_paramenum(open | pending | resolved | snoozed | all)Filter conversations by their workflow status.
One of open, pending, resolved, snoozed, or all. Defaults to open when omitted.
pageinteger1-based page account for paginating results.
Optional; defaults to the first page when omitted.
inbox_idstringThe id of the TikTok account to use, from GET /api/ext/omni_v2/tiktok/inboxes.
Use inboxes[].id (a UUID), not the numeric inboxes[].inbox_id. Optional while the project has one TikTok account; required once it has more than one.
Response
Successful Response
application/json
Validation Error
application/json