Skip to main content

Create or Replace Ticket Draft

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

Creates the ticket's shared draft, or replaces it — the endpoint for agents and automation writing a draft over the API. No version bookkeeping is needed: the caller may replace a draft it already holds, and the draft is attributed to the token's agent (it lights the ticket's Draft chip in the desk inbox and opens in the composer).

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

  • body_html (string, max 200000) — the draft as HTML, what the desk composer edits. Preferred. Required unless body is sent
  • body (string, max 65000) — plain-text draft, used when body_html is absent. Required unless body_html is sent
  • mode (optional, string, default reply) — reply (a public reply) or note (an internal note)
  • cc[] (optional, array, max 20, each a valid email, max 255) — the addresses the reply would copy
  • status_after (optional, string, nullable) — the status to set when the draft is sent. One of: open, in_progress, waiting_on_customer, awaiting_release, resolved, closed
  • attachments[] (optional, array, max 10) — file metadata only, each {name (required, max 255), size (optional integer, min 0)}. The files themselves ride the send, never the draft
  • version (optional, integer, min 0) — omit it for create-or-replace. Pass it to opt into the strict optimistic lock the desk uses: the save is refused with 409 unless it matches the stored draft's version
  • force (optional, boolean, default false) — take over a draft another agent holds

Responses

  • 201 — the draft was created (version 1)
  • 200 — an existing draft was replaced (version increments by one)
  • 409 — another agent holds the draft (or the passed version is stale). The body carries message naming the holder and draft, the current draft with its user. Nothing is overwritten; retry with force: true to take it over
  • 422 — validation failed (e.g. neither body_html nor body)
  • 403 — the token lacks the support:write scope, or the user is not a support agent who can see the ticket

The desk's own autosave uses PUT on the same path (versioned on every save). Sending a reply or an internal note on the ticket clears the draft automatically; DELETE discards it.

Authentication: Bearer token with the support:write scope, or an authenticated support agent session.

Request​

Responses​

OK

Response Headers
    Content-Type