Chat

Start a chat conversation

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.

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)

Headers

Idempotency-Keystring

Optional but recommended: 1 to 255 visible ASCII characters without spaces. The same key within 24 hours returns the same conversation.

Request body

channel'chat'

The channel. Only chat for now; it is also the default.

referencestring

Optional: your own id for this conversation, like a session or ticket id. Comes back in the conversation and its webhook.

metadataobject

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.

Response

The conversation, with the greeting as its first message.

idstring 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.

referencestring nullable required

Your own id for this conversation, as you sent it.

metadataobject required

Your metadata, as you sent it. The assistant never sees it.

languagestring 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.

turnsinteger required

Customer messages answered so far.

max_turnsinteger required

After this many turns the conversation closes (close_reason turn_limit).

created_atstring date-time required

When the conversation started.

last_message_atstring date-time nullable required

When the last message was sent.

closed_atstring 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_summaryboolean required

Whether the summary is ready. Fetch it with GET /conversations/{id}.

summary_ready_atstring date-time nullable required

When the summary was ready.

testboolean required

true for a conversation in test mode (hm_test_): real replies, free, with a low daily limit.

Changes

No recorded changes to this operation across all 1 revision of this API.