assistant.handoffs.create

Ask a person

POST/assistant/handoffs

Operation: assistant.handoffs.create
MCP tool: not exposed over MCP

Send a message to a human support agent, optionally with the assistant conversation attached. The assistant never does this by itself: it can say a person should take over, and this is the customer pressing the button. The request is WRITTEN DOWN before the email is attempted, so a mail outage delays it rather than losing it — ticket.status is sent when the support inbox already has it and queued when it is still being delivered, and in both cases the reference is final and the request needs no resending. The transcript, when attached, is the conversation as the SERVER stored it, not as the client claims it happened. A successful same-key retry reads the original ticket's current delivery state without submitting it again; failed means automatic retries have ended.

curl -X POST "https://api.gogoscreen.com/api/v1/assistant/handoffs" \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "category": "billing", "message": "<message>", "subject": "<subject>" }'

The shape of a request to this operation. The dashboard sends it with the signed in person's session; an API key is refused.

At a glance

Fact	Detail
Scopes	`assistant:use`
Credentials	a signed in dashboard session. An API key cannot be granted these scopes, so this operation is reachable only from a signed in dashboard session.
Rate limit	120 requests a minute per credential, in the `write` class.
Idempotency	Required. Send an `Idempotency-Key` header; a retry with the same key and the same body returns the stored answer with `Idempotent-Replayed: true`. The key is also written to the record this creates, so a retry cannot leave two behind. How idempotency works.
MCP tool	Not exposed over MCP.
Always sets	`Cache-Control: private, no-store`
Verified email	Required. An account whose email address is not verified meets `403 email_unverified` before the operation runs.
Audit	Every call is written to the audit log as `support_handoff`.

Request body

A JSON body is required. Unknown fields are refused rather than ignored, so a typo is a 400 validation_failed rather than a setting that silently did nothing.

Name	Type	Required	Description
category	string	Required	What the request is about. It routes the email and is the customer's choice, never the assistant's.one of: billing, bug, account, feature_request, other
message	string	Required	What the customer wants to say, in their own words. Stored and emailed as text.0–5000 characters
subject	string	Required	3–200 characters
conversationId	string	Optional	Attach this conversation. A conversation of another account is a 404. Omit for a request that started outside the assistant.format: uuid
includeTranscript	boolean	Optional	Attach the conversation's last fifty turns to the ticket. Absent means NO: a conversation is only ever copied into a support ticket because the customer asked for it.Default `false`

Response

Answers 201. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

201 Created

Ask a person

201 Created body
Name	Type	Description
contactEmail	string	Where the reply will go — the address on the signed-in account, echoed back so the panel can say so.
expectedReply	string	How long an answer usually takes.
ticket	object
category	string	one of: billing, bug, account, feature_request, other
createdAt	string	format: date-time
id	string
reference	string \| null	What to quote when you write to support about this: `GS-` and eight characters.
status	string	`sent` means the support inbox has it. `queued` means it is written down and being retried. `failed` means delivery is unconfirmed and automatic retries have ended; contact support directly with the reference.one of: queued, sent, failed
subject	string

201 Created headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.
`Idempotent-Replayed`	Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

Code	Status	When it happens	What to do
idempotency_key_required	400	A mutating operation arrived over HTTP with no `Idempotency-Key` header. It is refused before the body is parsed, so a caller missing both learns about both at once.	Add an `Idempotency-Key` header of up to 128 characters, unique to this request. Over MCP the same value goes in the `idempotencyKey` tool argument.
validation_failed	400	The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.	Read `details.issues`. Each entry carries a `path`, a `message` and a machine readable `code`. Fix every named field and send the request again; the same body always fails the same way.
unauthorized	401	No credential was presented, or the key is unknown, revoked or expired, or an `X-API-Key` header carried something that is not an API key. `details.reason` says which.	Send `Authorization: Bearer gsk_live_…`. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in `Authorization`, never in `X-API-Key`.
feature_disabled	403	The operation sits behind a feature flag this deployment has switched off.	Nothing a caller can change. Stop calling the operation, or ask the operator to enable it.
forbidden_scope	403	The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. `keys.` and `assistant.` are user only and can never be called by a key.	`details.requiredScopes` and `details.missingScopes` name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When `details.allowedActors` is present, no key can call this operation at all.
conversation_not_found	404	No conversation with that id belongs to this account. Another account's conversation answers the same 404, so this does not say whether the id exists.	Check the id. Read the current conversation to find the one to resume.
not_found	404	No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.	Check the id. Do not treat this as a permissions problem.
conflict	409	The request conflicts with the state the resource is in, and no more specific code applies.	Re-read the resource and decide from its current state. Retrying the same request unchanged will not help.
idempotency_conflict	409	That idempotency key has already been used on this operation with a different request body.	Use a fresh key for a different request. A key stands for one intent, not for one attempt.
idempotency_in_progress	409	The first request under that key is still being worked. Two concurrent identical requests both reach the store and one of them is told this.	Wait the `Retry-After` seconds, which is 2, and send exactly the same request again with the same key. Do not change the body and do not mint a new key.
payload_too_large	413	The request body is over the transport's limit: 256 kb over HTTP, 1 mb over MCP.	Send less. `details.limit` carries the limit. Version 1 has no upload operations, so a body this size is usually a mistake.
unsupported_media_type	415	The request carried a body whose `Content-Type` is not `application/json`, whose charset is not utf-8, or whose `Content-Encoding` this API does not decode. A body nobody can read would otherwise be silently discarded.	Send `Content-Type: application/json` and utf-8 bytes. `details` names the charset, encoding or content type that was objected to.
handoff_limit	429	This account has sent support as many messages as it may in the last hour.	Wait for `details.resetAt` and send it again. Messages already sent were received.
rate_limited	429	The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. `details.scope` is `minute`, `day` or `account`, or `global` when the product's own daily cap on voice previews is spent.	Wait the `Retry-After` seconds and retry. `details.limit` and `details.resetAt` say what was hit and when it reopens. The `RateLimit-*` headers on every answer let a client pace itself before it gets here.
internal_error	500	An unhandled failure inside this API. The original message is logged and never answered.	Retry once, then quote `requestId` to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.
handoff_failed	502	The message to support could not be recorded, the account has no address support could reply to, or a retry could not read the original request's current state. `details.reason` says which.	Try again shortly with the same Idempotency-Key, so a retry cannot send it twice. When `details.reason` is `no_contact_email`, the account needs an email address first.