Tickets

Quick Overview

List, view, and manage tickets including messages, labels, queue assignment, transfer, and status changes.

List Tickets

GET /v1/tickets

List all tickets with pagination and search.

Query Parameters

Parameter	Type	Default	Description
searchParam	string	-	Search term.
pageNumber	integer	1	Page number.
pageSize	integer	-	Number of results per page.
sortBy	string	-	Sort order: asc or desc.

Response

{
  "tickets": [
    {
      "id": "ticket_abc123",
      "status": "OPEN",
      "contactId": "contact_xyz789",
      "userId": null,
      "queueId": null
    }
  ],
  "count": 1,
  "hasMore": false
}

Get a Ticket

GET /v1/tickets/{ticketId}

Get details for a single ticket.

Path Parameters

Parameter	Type	Required	Description
ticketId	string	Yes	Ticket ID.

Response

{
  "ticket": {
    "id": "ticket_abc123",
    "status": "OPEN",
    "contact": {},
    "user": null,
    "queue": null,
    "labels": []
  }
}

Errors

Status	Error Code	Description
404	ERR_TICKET_NOT_FOUND	Ticket not found.

List Ticket Messages

GET /v1/tickets/{ticketId}/messages

List messages for a ticket with pagination.

Path Parameters

Parameter	Type	Required	Description
ticketId	string	Yes	Ticket ID.

Query Parameters

Parameter	Type	Default	Description
pageNumber	integer	1	Page number.
pageSize	integer	-	Number of results per page.

Response

{
  "messages": [
    {
      "id": "msg_abc123",
      "body": "Hello",
      "fromMe": false,
      "channel": "WHATSAPP"
    }
  ],
  "count": 1,
  "hasMore": false
}

Errors

Status	Error Code	Description
404	ERR_TICKET_NOT_FOUND	Ticket not found.

Add Labels to a Ticket

POST /v1/tickets/{ticketId}/labels

Add one or more labels to a ticket.

Path Parameters

Parameter	Type	Required	Description
ticketId	string	Yes	Ticket ID.

Request Body

{
  "labelSlugs": ["vip", "urgent"]
}

Field	Type	Required	Description
labelSlugs	array	Yes	Label slugs to add.

Response

{
  "ticket": {
    "id": "ticket_abc123",
    "labels": [
      { "id": "label_abc123", "slug": "vip" },
      { "id": "label_def456", "slug": "urgent" }
    ]
  }
}

Errors

Status	Error Code	Description
400	ERR_LABEL_SLUGS_REQUIRED	Label slugs required.
404	ERR_TICKET_NOT_FOUND or ERR_LABEL_NOT_FOUND	Ticket or label not found.

Remove Labels from a Ticket

DELETE /v1/tickets/{ticketId}/labels

Remove one or more labels from a ticket.

Path Parameters

Parameter	Type	Required	Description
ticketId	string	Yes	Ticket ID.

Request Body

{
  "labelSlugs": ["vip"]
}

Field	Type	Required	Description
labelSlugs	array	Yes	Label slugs to remove.

Response

{
  "ticket": {
    "id": "ticket_abc123",
    "labels": []
  }
}

Errors

Status	Error Code	Description
400	ERR_LABEL_SLUGS_REQUIRED	Label slugs required.
404	ERR_TICKET_NOT_FOUND	Ticket not found.

Assign Ticket to a Queue

PUT /v1/tickets/{ticketId}/queue

Assign or unassign a ticket to a queue.

Path Parameters

Parameter	Type	Required	Description
ticketId	string	Yes	Ticket ID.

Request Body

{
  "queueId": "queue_abc123"
}

To unassign, set queueId to null:

{
  "queueId": null
}

Field	Type	Required	Description
queueId	string | null	Yes	Queue ID to assign, or null to unassign.

Response

{
  "ticket": {
    "id": "ticket_abc123",
    "queueId": "queue_abc123",
    "queue": { "id": "queue_abc123", "name": "Sales" }
  }
}

Errors

Status	Error Code	Description
404	ERR_TICKET_NOT_FOUND or ERR_QUEUE_NOT_FOUND	Ticket or queue not found.

Transfer a Ticket

PUT /v1/tickets/{ticketId}/transfer

Transfer a ticket to a user and optionally assign to a queue.

Path Parameters

Parameter	Type	Required	Description
ticketId	string	Yes	Ticket ID.

Request Body

{
  "userId": "user_abc123",
  "queueId": "queue_def456"
}

Field	Type	Required	Description
userId	string	Yes	User ID to transfer to.
queueId	string	Yes	Queue ID to assign.

Response

{
  "ticket": {
    "id": "ticket_abc123",
    "userId": "user_abc123",
    "queueId": "queue_def456",
    "user": { "id": "user_abc123", "name": "Agent Name" },
    "queue": { "id": "queue_def456", "name": "Sales" }
  }
}

Errors

Status	Error Code	Description
404	ERR_TICKET_NOT_FOUND, ERR_USER_NOT_FOUND_IN_WORKSPACE, or ERR_QUEUE_NOT_FOUND	Ticket, user, or queue not found.

Update Ticket Status

PUT /v1/tickets/{ticketId}/status

Update the status of a ticket.

Path Parameters

Parameter	Type	Required	Description
ticketId	string	Yes	Ticket ID.

Request Body

{
  "status": "IN_PROGRESS"
}

When setting status to IN_PROGRESS and no assignee is set, you must provide userId:

{
  "status": "IN_PROGRESS",
  "userId": "user_abc123"
}

Field	Type	Required	Description
status	string	Yes	New ticket status.
userId	string	No	User ID to assign when setting status to IN_PROGRESS and no assignee exists.

Response

{
  "ticket": {
    "id": "ticket_abc123",
    "status": "IN_PROGRESS",
    "userId": "user_abc123"
  }
}

Errors

Status	Error Code	Description
400	ERR_USER_ID_REQUIRED	userId required when starting progress without an assignee.
404	ERR_TICKET_NOT_FOUND or ERR_USER_NOT_FOUND_IN_WORKSPACE	Ticket or user not found.