Ticket Lifecycle

How tickets work in ZapTicket — references, status workflow, timestamps, and per-tenant uniqueness.

Overview

Tickets are structured, asynchronous support items for issues that need tracking beyond a real-time conversation. They have a unique reference number, priority, assignee, tags, and a formal status workflow.

Tickets can be created directly by agents or converted from conversations. Either way, they follow the same lifecycle.

Reference Numbers

Every ticket gets an auto-incrementing reference in the format ZT-XXXX. This is a human-friendly identifier that agents and visitors can use to refer to specific issues.

Reference Format

ZT-1001  (first ticket in a workspace)
ZT-1002  (second ticket)
ZT-1042  (42nd ticket)
...
ZT-9999
ZT-10000 (no upper limit)

💡References are unique per tenant, not globally. Two different workspaces can both have a ticket ZT-1001 — they're completely independent. The counter starts at 1001 for every new workspace.

Status Workflow

Ticket Status Flow

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   Open ─────────► In Progress ─────────► Resolved ────► Closed │
│     │                  │                    │              │  │
│     │                  │                    │              │  │
│     │                  └────── Reopen ◄─────┘              │  │
│     │                                                     │  │
│     └──────────────────── Reopen ◄────────────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Open

Initial state. The ticket has been created but no work has started. It sits in the queue waiting to be picked up or triaged.

In Progress

Work has begun. An agent is actively investigating or working on the issue. This signals to the team that someone owns it.

Resolved

The issue has been addressed. A fix has been deployed, an answer provided, or the request fulfilled. The resolvedAt timestamp is set automatically when transitioning to this state.

Closed

Final confirmation that no further action is needed. Typically set after verifying the resolution holds. Closed tickets can still be reopened if the issue recurs.

Timestamps

Key Timestamps

{
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-01-16T14:30:00Z",
  "resolvedAt": "2024-01-16T14:30:00Z"
}

createdAt — Set once when the ticket is created. Never changes.
updatedAt — Updated on every modification (status change, field edit, reassignment).
resolvedAt — Set when status changes to "resolved". Cleared if the ticket is reopened.

💡The resolvedAt timestamp enables resolution time metrics. You can calculate time-to-resolution as resolvedAt - createdAt for reporting and SLA tracking.

Creating Tickets

Tickets can be created through two paths:

1. Direct Creation

Agents create tickets directly via POST /tickets for issues that don't start as conversations — bug reports from internal testing, feature requests from meetings, etc.

2. Conversion from Conversation

When a real-time conversation reveals an issue that needs tracked follow-up, agents can convert it via POST /conversations/{id}/convert-to-ticket. The ticket is linked back to the original conversation.

Conversion Behavior

Conversation conv_abc123 converted to ticket:
  → New ticket created: tkt_xyz789 (ZT-1044)
  → ticket.conversationId = "conv_abc123"
  → Conversation and ticket have independent lifecycles
  → Conversation can be closed while ticket remains open
  → A conversation can only be converted once (409 on retry)

Priority Levels

Priority Scale

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

Priority is informational and used for sorting/filtering. ZapTicket does not enforce SLA deadlines based on priority — that's left to your team's workflow.

Per-Tenant Uniqueness

Several ticket properties are unique within a tenant but not globally:

Reference (ZT-XXXX) — unique per tenant, auto-incremented
Internal ID — globally unique UUID
Tags — shared namespace within a tenant

This means Workspace A's ZT-1001 is a completely different ticket from Workspace B's ZT-1001. Use the internal id field for programmatic references and the reference field for human communication.