---
title: "Send a visitor message and get the reply (public)"
method: POST
path: "/public/conversations/{id}/messages"
tags: ["Chat widget"]
---

# Send a visitor message and get the reply (public)

`POST /public/conversations/{id}/messages`

## Request

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

Called by the chat widget for every message the visitor types. Needs the public chat token in ?token=, the Origin header and X-Conversation-Token. Works like POST /conversations/{id}/messages: the same assistant, the same checks, and with `Accept: text/event-stream` the same Server-Sent Events (delta, then done or error). Limits: 2000 characters per message, 30 turns per conversation, 6 messages per minute per conversation and 20 per minute per IP address. In live mode, every reply is billed per use from your prepaid balance and counts toward the public chat's daily spending limit (counted at a safe 3 cents a reply); beyond that limit, the request returns public_chat_limit_reached.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Conversation-Token` string, required
- `Accept` 'application/json' | 'text/event-stream'

## Request body

- ChatMessageInput: One message from the customer.
  - `text` string, required: What the customer typed, at most 2000 characters. Send it as is; it is never treated as an instruction to the assistant.

## Response `200`

The visitor's message and the assistant's reply.

- PublicChatTurn: One turn in the widget: the visitor's message and the assistant's reply.
  - `message` object, required: The visitor's message as stored.
    - `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.
  - `reply` object, required: The assistant's reply. Show this text.
    - `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` object, required: The conversation after this turn. status closed means the turn limit was reached.
    - `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_).

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: invalid_chat_token, chat_token_revoked, invalid_conversation_token.
- `402`: Payment Required: test_free_replies_used.
- `403`: Forbidden: origin_not_allowed.
- `404`: Not Found: not_found.
- `409`: Conflict: conversation_closed, conversation_busy, conversation_turn_limit_reached.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited, public_chat_limit_reached.
- `500`: Internal Server Error: internal_error.
- `502`: Bad Gateway: upstream_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)