Tickets

Endpoints for creating, listing, and managing support tickets. Tickets can be created directly or converted from conversations.

Overview

Tickets are structured support items with a reference number (e.g. ZT-1001), priority, status workflow, and assignee. Unlike conversations which are real-time, tickets are asynchronous and suitable for issues that require investigation, escalation, or tracking.

Every ticket has a unique per-tenant reference in the format ZT-XXXX where the number auto-increments within the workspace.

Endpoints

List Tickets

GET/tickets

List tickets with filtering, sorting, and pagination.

Auth: Workspace token (agent)

Query Parameters
status       - Filter: "open", "in_progress", "resolved", "closed" (optional)
priority     - Filter: "low", "medium", "high", "urgent" (optional)
assigneeId   - Filter by assigned agent ID (optional)
tag          - Filter by tag name (optional)
search       - Search title and description (optional)
page         - Page number, default 1
pageSize     - Results per page, default 25, max 100
sortBy       - "createdAt", "updatedAt", "priority", "reference" (default: "createdAt")
sortOrder    - "asc" or "desc" (default: "desc")
Response 200
{
  "data": [
    {
      "id": "tkt_abc123",
      "reference": "ZT-1042",
      "title": "Cannot export invoice PDF",
      "description": "When I click export, nothing happens...",
      "status": "open",
      "priority": "high",
      "assigneeId": "agt_xyz789",
      "assignee": {
        "id": "agt_xyz789",
        "fullName": "Sarah Agent"
      },
      "tags": ["billing", "bug"],
      "conversationId": "conv_def456",
      "createdBy": "visitor",
      "createdAt": "2024-01-16T09:00:00Z",
      "updatedAt": "2024-01-16T09:00:00Z",
      "resolvedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 87,
    "totalPages": 4
  }
}

Create Ticket

POST/tickets

Create a new ticket directly (not from a conversation).

Auth: Workspace token (agent)

Request Body
{
  "title": "Add dark mode to dashboard",
  "description": "Users have requested a dark mode option for the agent dashboard. This should respect system preferences by default.",
  "priority": "medium",
  "assigneeId": "agt_xyz789",
  "tags": ["feature-request", "dashboard"]
}

Only title is required. All other fields are optional. If priority is not set, it defaults to "medium".

Response 201
{
  "id": "tkt_new456",
  "reference": "ZT-1043",
  "title": "Add dark mode to dashboard",
  "description": "Users have requested a dark mode option...",
  "status": "open",
  "priority": "medium",
  "assigneeId": "agt_xyz789",
  "assignee": {
    "id": "agt_xyz789",
    "fullName": "Sarah Agent"
  },
  "tags": ["feature-request", "dashboard"],
  "conversationId": null,
  "createdBy": "agent",
  "createdAt": "2024-01-16T10:00:00Z",
  "updatedAt": "2024-01-16T10:00:00Z",
  "resolvedAt": null
}

Get Ticket

GET/tickets/{id}

Get full details of a single ticket.

Auth: Workspace token (agent)

Response 200
{
  "id": "tkt_abc123",
  "reference": "ZT-1042",
  "title": "Cannot export invoice PDF",
  "description": "When I click export on the billing page, nothing happens. I've tried Chrome and Firefox. Console shows a 500 error from the API.",
  "status": "in_progress",
  "priority": "high",
  "assigneeId": "agt_xyz789",
  "assignee": {
    "id": "agt_xyz789",
    "fullName": "Sarah Agent"
  },
  "tags": ["billing", "bug"],
  "conversationId": "conv_def456",
  "conversation": {
    "id": "conv_def456",
    "visitorName": "John Doe",
    "status": "closed"
  },
  "createdBy": "visitor",
  "createdAt": "2024-01-16T09:00:00Z",
  "updatedAt": "2024-01-16T11:30:00Z",
  "resolvedAt": null
}

Update Ticket

PATCH/tickets/{id}

Update ticket fields. All fields in the body are optional.

Auth: Workspace token (agent)

Request Body
{
  "title": "Cannot export invoice PDF — fixed in v2.3",
  "status": "resolved",
  "priority": "high",
  "assigneeId": "agt_xyz789",
  "tags": ["billing", "bug", "fixed"]
}
Response 200
{
  "id": "tkt_abc123",
  "reference": "ZT-1042",
  "title": "Cannot export invoice PDF — fixed in v2.3",
  "status": "resolved",
  "priority": "high",
  "assigneeId": "agt_xyz789",
  "tags": ["billing", "bug", "fixed"],
  "updatedAt": "2024-01-16T14:00:00Z",
  "resolvedAt": "2024-01-16T14:00:00Z"
}
💡When status changes to "resolved", the resolvedAt timestamp is automatically set. If the ticket is reopened, resolvedAt is cleared.

Convert Conversation to Ticket

POST/conversations/{id}/convert-to-ticket

Create a ticket from an existing conversation. Links the ticket back to the conversation.

Auth: Workspace token (agent)

Request Body
{
  "title": "Billing issue — duplicate charge",
  "priority": "high",
  "assigneeId": "agt_xyz789",
  "tags": ["billing"]
}

Only title is required. The ticket description is auto-generated from the conversation's first few messages if not provided explicitly.

Response 201
{
  "id": "tkt_conv789",
  "reference": "ZT-1044",
  "title": "Billing issue — duplicate charge",
  "description": "Auto-generated from conversation conv_abc123",
  "status": "open",
  "priority": "high",
  "assigneeId": "agt_xyz789",
  "conversationId": "conv_abc123",
  "createdBy": "agent",
  "createdAt": "2024-01-16T15:00:00Z"
}
⚠️A conversation can only be converted to a ticket once. Attempting to convert again returns 409 Conflict.

Status Values

  • open — Ticket created, no work started
  • in_progress — Actively being worked on
  • resolved — Fix or answer delivered, sets resolvedAt
  • closed — Confirmed resolved, no further action needed

Priority Values

  • low — Nice to have, no time pressure
  • medium — Standard priority (default)
  • high — Important, should be addressed soon
  • urgent — Critical issue, needs immediate attention