TikTok
Filter TikTok conversations
List TikTok conversations on one of the project's TikTok accounts using a structured filter payload instead of simple query parameters. The request body carries a filters array of filter objects, and results are paginated with the page query parameter. The response shape matches the generic list endpoint, including meta counts and a payload array of conversations.
curl --request POST \
--url 'https://api.nabrah.ai/api/ext/omni_v2/tiktok/filter' \
--header 'X-API-Key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"filters": []
}'{
"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
}
]
}Filters & pagination
Combine the structured filters body with the page query parameter to page through matching conversations.
filtersAn array of filter objects describing the conditions to match. Pass an empty array for no constraints, or add filter conditions; each condition needs attribute_key, filter_operator and values to narrow the result set.
filtersThe response meta counts (all/mine/unassigned/assigned) are independent of the current page.
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
pageinteger1-based page account for paginating filtered results.
Optional; defaults to the first page when omitted.
page_sizeintegerstatusenum(open | pending | resolved | snoozed | all)assignee_typeenum(all | me | unassigned | assigned)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.
Body
application/json{
"filters": []
}Response
Successful Response
application/json
Validation Error
application/json