Create Conversation

POST

/v2/conversations/service-account/create

Despite the name, this is really a get-or-create operation: it finds or creates a contact by phone number, then finds or creates (and reopens if closed) a conversation between that contact and a channel — optionally assigning it to a user or AI agent in the same call.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

Returns the found-or-created conversation, plus a top-level contactId convenience field (duplicate of conversation.contactId).

Bodyapplication/json

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.voxa.sa/v2/conversations/service-account/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "channelId": "3a197b...............",
    "phoneNumber": "+966500888777",
    "contactName": "Ahmed Ali",
    "assignToUserId": null,
    "assignToAiAgentId": null
}'

Response Example

{
    "conversation": {
        "id": "3a1eef...............",
        "sentiment": 1,
        "status": 2,
        "lastActivityAt": "2026-03-11T19:35:14.357535",
        "contactId": "3a1dc9...............",
        "contactName": "+966115001211",
        "contactType": 1,
        "phoneNumber": "+966115001211",
        "channelId": "3a1da0...............",
        "assigneeId": null,
        "assignedAiAgentId": null,
        "isAiAssignee": false,
        "assigneeName": null,
        "channel": {
            "id": "3a1da0...............",
            "name": "هاتف | الرقم الرسمي",
            "type": 3,
            "icon": "📱",
            "phoneNumber": null
        },
        "lastEventSourceType": 1,
        "lastEventDirection": 2,
        "lastEventStatus": "Completed",
        "lastEventPreviewBody": null,
        "lastEventOccurredAt": "2026-03-11T19:35:14.357535",
        "lastEventsCount": 0,
        "tags": [],
        "unreadCount": 0,
        "isPinned": false
    },
    "contactId": "3a1dc9..............."
}

Modified at 2026-06-22 14:18:58

List Conversations

Assign Conversation