Get or create thread

get

Retrieve or create a thread for a customer on a specific channel and get its messages in multimodal format.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

Bearer {apikey}

Path parameters

agentIdstringRequired

The ID of the agent.

customerIdstringRequired

The ID of the customer.

channelstringRequired

The channel name. Supported channels are: facebook, instagram, whatsapp, tiktok, telegram, widget_chatbot, or any channel starting with 'chatbot.' (e.g., 'chatbot.web', 'chatbot.mobile'). Note: For chatbot channels and widget_chatbot alias, the customer must have a widget_chatbot.id field. When using widget_chatbot, the API resolves to an existing chatbot.* thread for the customer.

Example: {"value":"facebook","summary":"Facebook channel"}

Query parameters

limitintegerOptional

Optional limit for the number of messages to return (starting from the last message). If not provided, returns all messages.

Responses

200

Successful Response

application/json

idstringRequired

The thread ID.

agentIdstringRequired

The agent ID.

customerIdstringRequired

The customer ID.

statusstringRequired

The thread status (e.g., 'active', 'inactive').

aiResponseStatusstringOptional

The AI response status (e.g., 'enabled', 'disabled').

createdAtstring · date-timeRequired

The thread creation timestamp.

updatedAtstring · date-timeRequired

The thread last update timestamp.

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/v1/agents/{agentId}/customers/{customerId}/threads/{channel}

HTTPcURLJavaScriptPython

GET /v1/agents/{agentId}/customers/{customerId}/threads/{channel} HTTP/1.1
Host: api.voxity.ai
Authorization: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "agentId": "text",
  "customerId": "text",
  "from": {
    "channel": "text",
    "id": "text"
  },
  "status": "text",
  "aiResponseStatus": "text",
  "createdAt": "2026-04-02T08:39:25.437Z",
  "updatedAt": "2026-04-02T08:39:25.437Z",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "text"
        }
      ]
    }
  ]
}