--- title: "Start a chat conversation" method: POST path: "/conversations" tags: ["Chat"] --- # Start a chat conversation `POST /conversations` ## Request - Base URL: `https://api.hypamoon.com/api/v1` - URL: `https://api.hypamoon.com/api/v1/conversations` - Auth: one of: - HTTP bearer - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `chat:write`) Starts a text chat with the assistant of the project: the same assistant that answers your phone, with the same instructions, languages, opening hours and website (set with PUT /assistant). The response contains the fixed greeting as the first message; send the customer's messages with POST /conversations/{id}/messages. Call this from your backend, never from a browser: the API key is a server-side secret. A website chat goes through your own server, which adds the key, or uses the chat widget with a public chat token (POST /chat-tokens). A live key needs the company verification level (company details, spending cap, payment method, a verified phone and one payment confirmed with your bank: iDEAL or a card with 3D Secure). At most 20 new conversations per minute and 1000 per day per project. With a test key the assistant gives real answers: the first 20 replies per day are free, after that each reply is deducted from the prepaid balance of your live project the same way as live, billed per use (402 test_free_replies_used without balance or saved card). At most 25 test conversations per day. Send an Idempotency-Key so a retry returns the same conversation. ## Headers - `Idempotency-Key` string ## Request body - ConversationInput: A new chat conversation with the assistant of the project. - `channel` 'chat': The channel. Only chat for now; it is also the default. - `reference` string: Optional: your own id for this conversation, like a session or ticket id. Comes back in the conversation and its webhook. - `metadata` object: Optional: up to 20 keys with a string (at most 500 characters), number or boolean, for your own use. Stored and returned as is; the assistant never sees it. - `customer` object: Optional: what your app already knows about the customer, for example from their login. The assistant may use it to address the customer and to confirm how to reach them; it is treated as data, never as instructions. - `name` string - `phone` string - `email` string, email ## Response `201` The conversation, with the greeting as its first message. - ConversationDetail: A conversation with its messages and summary. - `id` string, uuid, required: The id of the conversation. - `channel` 'chat' | 'widget', required: The channel: chat when your app started it with an API key, widget when a visitor started it in the chat widget on a website (public chat token). - `status` 'open' | 'closed', required: open: takes messages. closed: takes no more messages; the summary follows. - `reference` string, nullable, required: Your own id for this conversation, as you sent it. - `metadata` object, required: Your metadata, as you sent it. The assistant never sees it. - `customer` object, required: What your app told us about the customer when the conversation started. - `name` string, nullable, required - `phone` string, nullable, required - `email` string, nullable, required - `language` string, required: The language the assistant opened in (nl, en, de, fr or es). It replies in the customer's language when that is one of its languages. - `turns` integer, required: Customer 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: closed: POST /conversations/{id}/close. inactive: no message for 30 minutes. turn_limit: max_turns reached. - `has_summary` boolean, required: Whether the summary is ready. Fetch it with GET /conversations/{id}. - `summary_ready_at` string, date-time, nullable, required: When the summary was ready. - `test` boolean, required: true for a conversation in test mode (hm_test_): real replies, free, with a low daily limit. - `messages` ChatMessage[], required: All messages, oldest first, starting with the fixed greeting. - `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. - `summary` Summary, required: The summary of a call. - `text` string, nullable, required: The summary in a few sentences. - `topics` string[], required: What the call was about. - `sentiment` 'positive' | 'neutral' | 'negative' | 'null', nullable, required: The mood of the caller. - `action_items` string[], required: What someone has to do after this call. - `next_step` string, nullable, required: The agreed next step, if any. ## Other responses - `400`: Bad Request: idempotency_key_invalid, invalid_json. - `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted. - `402`: Payment Required: payment_mandate_missing, billing_blocked, insufficient_balance. - `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required. - `409`: Conflict: idempotency_key_reused, idempotency_request_in_progress. - `422`: Unprocessable Content: validation_failed, company_details_missing, spend_cap_missing, assistant_not_configured. - `429`: Too Many Requests: rate_limited, conversation_limit_reached. - `500`: Internal Server Error: internal_error. - `503`: Service Unavailable: service_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)