List Conversations

Lists conversations for a specific channel, with filtering by status, assignee, contact, tags, date range, lost/unread state, and pagination.

channelId is supplied directly in the URL path.

Filter notes:

assigneeUserIds, contactIds, tagIds — comma-separated GUIDs in a single query string value (e.g. ?assigneeUserIds=id1,id2), not a repeated query param or JSON array.

getUnAssigned — include conversations with no assignee.

PhoneNumber — case-sensitive substring filter on the contact's phone number. Returns only conversations where the contact's value contains the given string (e.g. ?PhoneNumber=966 matches any number containing "966"; ?PhoneNumber=DOESNOTEXIST returns totalCount: 0) Note: Don't use +.

fromDate/toDate — ⚠️ expected in UTC+3, not UTC. The server subtracts 3 hours internally, assuming you've sent Saudi local time. Sending true UTC here will silently shift your filter window by 3 hours.

isLost — conversations whose last event was inbound but never successfully addressed (missed/failed call, unanswered WhatsApp message).

isUnread — filter by unread state.

skipCount/maxResultCount/sorting — standard ABP paging.

Request

Authorization

OAuth 2.0

Client Credentials

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Token URL: https://api.voxa.sa/connect/token

Scopes:

VoxaAPI-Access Voxa API as a service account

Query Params

curl --location --globoff 'https://api.voxa.sa/v2/conversations/service-account/channels/{{channelId}}?status=undefined&assigneeUserIds=undefined&getUnAssigned=undefined&contactIds=undefined&tagIds=undefined&Name=undefined&PhoneNumber=undefined&fromDate=undefined&toDate=undefined&isLost=undefined&isUnread=undefined&sorting=undefined&skipCount=undefined&maxResultCount=undefined'

{ "totalCount": 2461, "items": [ { "id": "3a21fc...............", "sentiment": 1, "status": 1, "lastActivityAt": "2026-06-21T13:15:47.459339", "contactId": "3a21fb...............", "contactName": "Ahmed Noshy | Hatif Co", "contactType": 1, "phoneNumber": "+966501234567", "channelId": "3a1bf3...............", "assigneeId": null, "assignedAiAgentId": null, "isAiAssignee": false, "assigneeName": null, "channel": { "id": "3a1bf3...............", "name": "هاتف", "type": 3, "icon": "📱", "phoneNumber": null }, "lastEventSourceType": null, "lastEventDirection": null, "lastEventStatus": "", "lastEventPreviewBody": null, "lastEventOccurredAt": null, "lastEventsCount": 0, "tags": [], "unreadCount": 0, "isPinned": false } ] }

List Conversations

Request

Responses