Skip to main content
A ticket is one piece of support work inside a person’s conversation: it opens when the customer writes in (or the team starts one), is answered, and is solved and in time closed. Through the API they are the same tickets the panel’s Tickets screen and the Inbox show — changes you make appear there, with the same trail, and changes your team makes reach you as webhook events.
  • The endpoints exist when the account’s plan includes Tickets; otherwise every one answers 404 module_off.
  • You need a key with tickets:read to see tickets, their notes and history, and categories, and tickets:write to open, change, solve and close them, add notes and manage categories (see Keys and scopes).
  • Teammates are named by their email, as assignee. The conversation a ticket lives in is named by the id /v1/conversations uses: the contact’s id.
  • Every change made through the API is signed API · <key name> in the ticket’s history and on its notes.

​
Tickets

​
Notes

Internal notes are for the team: they are never sent to the customer.

​
Categories

​
How tickets behave

A ticket is open or pending while it is being worked on — live — then solved, then closed.
  • One live ticket per conversation. Opening a ticket on a conversation that already has one open or pending solves that one first. Reopening a solved ticket is refused while another is live there.
  • The ticket and its conversation stay in step. A live ticket’s priority and assignee are its conversation’s: changing them on the ticket changes the conversation, as in the Inbox. Opening or reopening a ticket opens its conversation.
  • Solving closes the conversation when the account keeps tickets and conversations in step (in its Ticket settings).
  • A closed ticket can’t reopen. Closing a live ticket solves it first. If the customer writes again later, a new ticket starts.
  • Tickets close by themselves. A solved ticket is closed once the account’s window has passed, and a pending ticket nobody answers is solved after a while — both set in Ticket settings.
  • Asking at the wrong moment is refused. Reopening a closed ticket, or one whose conversation has another live ticket, through POST …/reopen answers invalid_state (409); the same change through PATCH status answers invalid_request (400) with field status. Solving a solved ticket, or closing a closed one, leaves it as it is.

​
Webhook events

Rather than asking, subscribe a webhook endpoint to: Each carries the ticket, as ticket, in the shape GET /v1/tickets/{ticket_id} answers (without its history), and the change, as change — {kind, detail, by, at}, the entry it added to the ticket’s history:
Notes aren’t sent as events. Tickets closed automatically once the account’s window has passed are sent as ticket.closed too, with the ticket alone and no change.