Skip to main content

Send Agent Ticket Heartbeat

POST 
/api/support/agent/tickets/:ticket/heartbeat

The owner's sign of life: marks the ticket as being worked right now (work.working_now) for ttl_seconds, and records the owner's current working phase. Send it every couple of minutes while working; when heartbeats stop, working_now turns false once active_until passes. An AI-owned ticket with no heartbeat, progress or claim for 4 hours is reported as stale, and released automatically after 24 hours.

Required scope: support:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Only the current owner may heartbeat — anyone else (including the AI agent after a human took the ticket over) is refused with 409 not_owner and must stop working the ticket. A heartbeat records no timeline event; watchers of the ticket (including the customer) are notified only when working_now flips on or the phase changes.

Path parameters

  • ticket (integer) — the ticket id.

Request body

  • phase (string, required, max 40) — the owner's working phase, e.g. running, awaiting_human, drafting_reply. Shown to agents as work.phase, never to the customer.
  • ttl_seconds (integer, optional, nullable, 60–900) — how long this heartbeat holds. Default 300 (5 minutes).

The response is the updated ticket in the agent shape (see Get Agent Ticket for every field, including work).

Authentication: Bearer token with the support:write scope, or an authenticated session, from a caller with an active support role that can work tickets (the viewer role is read-only). No tenant context — this endpoint is central.

Request​

Responses​

OK

Response Headers
    Content-Type