---
title: "Start a conversation from the widget (public)"
method: POST
path: "/public/conversations"
tags: ["Chat widget"]
---

# Start a conversation from the widget (public)

`POST /public/conversations`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/public/conversations`
- Auth: API key in query parameter `token`

Called by the chat widget in the visitor's browser, with the public chat token in ?token= and the Origin header of the page. No API key. Starts a conversation (channel widget) with the assistant and returns the greeting and conversation_token: the secret of this conversation for this visitor, valid for 6 hours. Every later request for it needs that secret as X-Conversation-Token. With turnstile on (the default) send turnstile_token from the bot check; the widget shows that check in a frame on our host and does all of this for you. Limits: 3 new conversations per minute and 20 per hour per IP address, 30 per minute and 300 per hour per token, the token's daily limit (public_chat_limit_reached) and, in live mode, the project's daily spending limit. Your backend can read the conversation with GET /conversations/{id} and receives conversation.summary.ready like any other chat.

## Request body

- PublicConversationInput: Start a conversation from the chat widget.
  - `turnstile_token` string: The bot-check token from the challenge frame. Required when the public token has turnstile on (the default); the widget does this for you.

## Response `201`

The conversation with the greeting and its secret.

- PublicConversationStart: A new conversation from the widget, with its secret.
  - `conversation` PublicConversation, required: A conversation as the widget sees it: only what concerns the visitor. No metadata, customer details or summary; your backend reads those with GET /conversations/{id}.
    - `id` string, uuid, required: The id of the conversation.
    - `channel` 'widget', required: Always widget: started through a public chat token.
    - `status` 'open' | 'closed', required: open: takes messages. closed: takes no more messages.
    - `language` string, required: The language the assistant opened in.
    - `turns` integer, required: Visitor messages answered so far.
    - `max_turns` integer, required: After this many turns the conversation closes (close_reason turn_limit).
    - `created_at` string, date-time, required: When the conversation started.
    - `last_message_at` string, date-time, nullable, required: When the last message was sent.
    - `closed_at` string, date-time, nullable, required: When the conversation closed.
    - `close_reason` 'closed' | 'inactive' | 'turn_limit' | 'null', nullable, required: Why it closed: inactive after 30 minutes without a message, or turn_limit.
    - `test` boolean, required: true for a conversation through a test token (hm_pubtest_).
  - `messages` ChatMessage[], required: The fixed greeting, as the first message.
    - `id` string, uuid, required: The id of the message.
    - `role` 'customer' | 'assistant', required: Who wrote it: the customer, or the assistant (also the fixed greeting).
    - `text` string, required: The text.
    - `created_at` string, date-time, required: When the message was stored.
  - `conversation_token` string, required: The secret of this conversation, for this visitor only. Send it as X-Conversation-Token on every next request about this conversation. Keep it in the page (or sessionStorage), never in a URL.
  - `expires_at` string, date-time, required: When conversation_token stops working (6 hours after the start).

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: invalid_chat_token, chat_token_revoked.
- `402`: Payment Required: test_free_replies_used.
- `403`: Forbidden: origin_not_allowed, turnstile_failed.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited, public_chat_limit_reached.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: chat_unavailable.

---

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