Conversations — NexaDesk Docs

Access conversation data programmatically. List conversations, retrieve full message histories, and update conversation status.

List Conversations

Retrieve a paginated list of conversations with filtering and sorting.

GET /api/v1/external/conversations

Parameter	Type	Description
`status`	string	Filter by status: `open`, `pending`, `active`, `archived`, or `all`
`search`	string	Search by visitor name, email, or company
`tag`	string	Filter by tag (exact match)
`sort`	string	Sort field and direction. Allowed fields: `created_at`, `updated_at`
`limit`	number	Results per page (default 50, max 100)
`cursor`	string	Pagination cursor from previous response

bash

curl "https://chats.nexadesk.ai/api/v1/external/conversations?status=open&sort=updated_at:desc&limit=20" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx"

json

{
  "success": true,
  "data": [
    {
      "id": "c70f9500-a39c-42e5-b827-557766550002",
      "source": "widget",
      "status": "open",
      "tags": ["billing"],
      "created_at": "2026-03-20T08:00:00.000Z",
      "updated_at": "2026-03-20T08:45:00.000Z",
      "agent_id": null,
      "department_id": null,
      "visitor_name": "Sarah",
      "visitor_email": "[email protected]",
      "visitor_company": null,
      "agent_name": null,
      "last_message": "Can you tell me about your pricing plans?",
      "message_count": 6
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "total_count": 1,
    "limit": 20
  }
}

Get Conversation with Messages

Retrieve a single conversation with its full message history.

GET /api/v1/external/conversations?id={conversation_id}

bash

curl "https://chats.nexadesk.ai/api/v1/external/conversations?id=c70f9500-a39c-42e5-b827-557766550002" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx"

json

{
  "success": true,
  "data": {
    "conversation": {
      "id": "c70f9500-a39c-42e5-b827-557766550002",
      "source": "widget",
      "status": "open",
      "tags": ["billing"],
      "created_at": "2026-03-20T08:00:00.000Z",
      "updated_at": "2026-03-20T08:45:00.000Z",
      "visitor_name": "Sarah",
      "visitor_last_name": null,
      "visitor_email": "[email protected]",
      "visitor_phone": null,
      "visitor_company": null,
      "agent_name": null,
      "agent_last_name": null,
      "agent_email": null
    },
    "messages": [
      {
        "id": "msg-001",
        "sender_type": "visitor",
        "content": "Hi, I have a question about pricing",
        "attachments": null,
        "status": "delivered",
        "created_at": "2026-03-20T08:00:00.000Z",
        "sender_name": "Sarah"
      },
      {
        "id": "msg-002",
        "sender_type": "bot",
        "content": "Hello Sarah! I'd be happy to help with pricing information.",
        "attachments": null,
        "status": "delivered",
        "created_at": "2026-03-20T08:00:01.000Z",
        "sender_name": null
      }
    ],
    "message_count": 2
  }
}

Update Conversation

Update conversation status, assignment, or tags.

PATCH /api/v1/external/conversations?id={conversation_id}

All fields are optional. Only provided fields are updated.

Field	Type	Description
`status`	string	New status: `open`, `pending`, `active`, `archived`
`agent_id`	string (UUID) or null	Assign to an agent or unassign
`department_id`	string (UUID) or null	Assign to a department
`tags`	string[]	Replace tags array

bash

curl -X PATCH "https://chats.nexadesk.ai/api/v1/external/conversations?id=c70f9500-a39c-42e5-b827-557766550002" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "tags": ["billing", "escalated"]
  }'

json

{
  "success": true,
  "data": {
    "id": "c70f9500-a39c-42e5-b827-557766550002",
    "status": "active",
    "tags": ["billing", "escalated"],
    "updated_at": "2026-03-20T09:00:00.000Z"
  }
}