---
title: "Ask the assistant"
method: POST
path: "/assistant/messages"
tags: ["assistant"]
---

# Ask the assistant

`POST /assistant/messages`

## Request

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

Ask a question about GogoScreen and get an answer, in the same call. Without `conversationId` a new conversation is started; with one, the question continues that thread. The answer is plain text written from a knowledge base built out of this product's own limits; the assistant has no tools, cannot see anything about any other customer, and cannot change, refund or decide anything about an account — when a question needs a person it says so and sets `handoffSuggested`. `remainingToday` is how many more questions this account may ask before the daily cap; null when the cap is off.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `conversationId` string, uuid: Continue this conversation. Omit to start a new one. A conversation of another account is a 404.
  - `message` string, required: The question, as the customer typed it. Treated as text throughout: it is never part of the assistant's instructions, and credentials or card numbers in it are removed before it is stored.

## Response `201`

Ask the assistant

- object
  - `conversation` object, required
    - `createdAt` string, date-time, required
    - `id` string, required: The conversation's id. Pass it as `conversationId` to keep asking in the same thread.
    - `lastMessageAt` string, date-time, nullable, required: When the thread was last written to. Null on a conversation with no messages yet.
    - `messageCount` integer, required: How many questions the customer has asked in this thread. The per-conversation cap counts this, not the replies.
    - `status` 'open' | 'closed' | 'handed_off', required: `open` takes another question. `closed` and `handed_off` both refuse one with 409 `conversation_closed`; start a new conversation.
  - `remainingToday` integer, nullable, required
  - `reply` object, required
    - `content` string, required: Plain text. The assistant writes no HTML, no markdown headings and no links off this product.
    - `createdAt` string, date-time, required
    - `handoffSuggested` boolean, required: The assistant believes a person should take this. Offer the hand-off; it is never taken automatically.
    - `id` string, required
    - `role` 'user' | 'assistant', required
    - `topic` string, nullable, required: The assistant's own label for what the question was about — one of product, billing, account, api, troubleshooting, escalation, off_topic. Null on a customer's turn.

## 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. · `conversation_closed` — That conversation is closed. Start a new one. · `assistant_conversation_full` — This conversation has run as long as it can. Start a new one.
- `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. · `assistant_daily_limit` — You have reached today's limit for the assistant. You can still send a message to a person. · `ai_rate_limited` — You have asked a lot in the last hour. Try again shortly, or send a message to a person.
- `500`: `internal_error` — Something went wrong. Try again.
- `503`: `assistant_unavailable` — The assistant is unavailable right now. A person can still help.

---

[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)