Skip to main content

Hand Back Ticket to AI Agent

POST 
/api/support/agent/tickets/:ticket/hand-back

A human agent gives the ticket back to the AI agent with an instruction — the AI agent's next input. The AI agent becomes the owner (assignee, work.owner with is_bot: true), its working state starts fresh, and a ticket still at the received stage moves to picked_up. An internal handed_back event records the instruction; if the ticket has a shared reply draft, the draft is kept and travels with the instruction so the AI agent can build on it. The latest hand-back is returned as work.hand_back. The instruction is also queued for the AI agent as a hand_back instruction (see AI Control → Get AI Control Feed), which it picks up exactly once; work.pending_instructions counts it until then.

Required scope: support:write

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

Path parameters

  • ticket (integer) — the ticket id.

Request body

  • instruction (string, required, max 5000) — what the AI agent should do next.

Refused with a 422 on instruction when no AI agent is set up on the desk, when the caller is the AI agent itself, or when the AI agent is turned off for the ticket (turn it back on first).

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.

If this ticket was merged into another ticket, the request is refused with a 422 whose merged_into (id, number) names the live ticket — send the action there instead.

Request​

Responses​

OK

Response Headers
    Content-Type