---
title: "Ask a person"
method: POST
path: "/assistant/handoffs"
tags: ["assistant"]
---

# Ask a person

`POST /assistant/handoffs`

## Request

- Base URL: `https://api.gogoscreen.com/api/v1`
- URL: `https://api.gogoscreen.com/api/v1/assistant/handoffs`
- Auth: HTTP bearer

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.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `category` 'billing' | 'bug' | 'account' | 'feature_request' | 'other', required: What the request is about. It routes the email and is the customer's choice, never the assistant's.
  - `conversationId` string, uuid: Attach this conversation. A conversation of another account is a 404. Omit for a request that started outside the assistant.
  - `includeTranscript` boolean: 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.
  - `message` string, required: What the customer wants to say, in their own words. Stored and emailed as text.
  - `subject` string, required

## Response `201`

Ask a person

- object
  - `contactEmail` string, required: Where the reply will go — the address on the signed-in account, echoed back so the panel can say so.
  - `expectedReply` string, required: How long an answer usually takes.
  - `ticket` object, required
    - `category` 'billing' | 'bug' | 'account' | 'feature_request' | 'other', required
    - `createdAt` string, date-time, required
    - `id` string, required
    - `reference` string, nullable, required: What to quote when you write to support about this: `GS-` and eight characters.
    - `status` 'queued' | 'sent' | 'failed', required: `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.
    - `subject` string, required

## Other responses

- `400`: `validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice.
- `401`: `unauthorized` — Authentication is required.
- `403`: `forbidden_scope` — This credential does not carry the scope this operation needs. · `feature_disabled` — That feature is not available.
- `404`: `not_found` — No such resource. · `conversation_not_found` — No such conversation.
- `409`: `idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state.
- `413`: `payload_too_large` — That request body is too large.
- `415`: `unsupported_media_type` — That content type is not supported.
- `429`: `rate_limited` — Too many requests. Try again shortly. · `handoff_limit` — You have sent support several messages in the last hour. Try again shortly.
- `500`: `internal_error` — Something went wrong. Try again.
- `502`: `handoff_failed` — Your message could not be sent just now. Try again shortly.

---

[API](https://skmtc.dev/gogoscreen/apis/gogoscreen-api.md) · [All operations](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/revisions/2fd812319d75?raw)