POST /api/v1/handoff/ticket

Create escalation tickets suggestions from your own UI.

Request

Field	Type	Required	Description
agentId	string	Yes	The agent's public ID
visitorEmail	string	Yes	A valid email for follow-up
sessionId	string	No	Ties the ticket to an existing conversation. Auto-generated if omitted
note	string	No	4,000 chars max. Extra context for the team
history	array	No	{ role: "user" \| "assistant", content: string }[], last 12 turns used. Summarized into a subject and urgency automatically

const res = await fetch("https://app.humaner.io/api/v1/handoff/ticket", {
  method: "POST",
  headers: {
    Authorization: "Bearer hm_live_xxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agentId: "AGENT_ID",
    visitorEmail: "customer@example.com",
    note: "Customer needs a refund on order #4521"
  })
});

Response

200 OK

{
  "ok": true,
  "ticketId": "tkt_abc123",
  "liveChat": { "enabled": false }
}

liveChat=enabled only for tickets issued from the widget. API-sourced tickets can only escalate issues with email references.

Errors

Status	Meaning
400	agentId missing, or visitorEmail missing or invalid
401	Missing or invalid API key, or no Origin header and no key
403	Origin not allowed, or Human Desk is off for the organization
404	Agent not found
429	Rate limit hit (Retry-After header set)
500	Ticket creation failed. Safe to retry