Channels
Chat API
Create a Muchat API key, send messages from your server, and handle responses, conversation IDs, follow-up messages, and handoff state.
Overview
Use Chat API to add Muchat to your own application or service. The API channel creates a key for the selected agent; your application uses it to send messages and receive answers. Send requests from your server so the key is not included in public browser code.
What you can do
Send messages, continue a conversation with its returned ID, and display AI reply or human handoff status in your application.
Create an API key
Open the API channel
Choose your agent in the dashboard. Open API in Deploy and click Setup.
Create the key
Click Create API Key. The key appears under Manage Keys; select it to copy the value.
Configure it on your server
Store the value in your server’s MUCHAT_API_KEY environment variable. It is different from the agent ID and the widget’s websiteToken.
Send a message
Send POST /v2/chat with an Authorization: Bearer header. This example waits for the final JSON response:
curl --request POST 'https://api.mu.chat/v2/chat' \
--header "Authorization: Bearer $MUCHAT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"query":"Hello","stream":false}'Reply text is in data.message.parts. Each text part has type set to text, with its content in text. Read conversation information and the response outcome from data.metadata:
| Field | Use |
|---|---|
conversation_id | Conversation ID for sending the next message in the same chat |
external_message_id | Incoming message ID for tracking or retries |
finish_reason | Generation outcome, such as completed or suppressed |
bot_active | Whether AI is active for the conversation |
handoff_status | Human handoff state |
Continue a conversation
Send the previous response’s conversation_id with the next query in your request body. Wait for the earlier request to finish before sending another; a conversation with a reply in progress does not accept a concurrent message.
- You may assign a unique
external_message_idto each logical message. For a retry, keep that ID and body unchanged to avoid creating a duplicate message. - Reusing the same ID with different text or another body causes a conflict. Use a new ID for a new message.
- Treat a request without
conversation_idas the start of a conversation. Save the returned ID to continue it. - If
messageis empty or the outcome issuppressed, do not invent reply text. Check the AI pause and handoff state.
Troubleshooting
| Status | Check |
|---|---|
401 | Check the key and Bearer header format. |
403 | Check channel activation and your plan’s API access. |
409 | Check for a reused message ID with a changed body, concurrent requests, or a closed conversation. |
422 | Send valid JSON and avoid an empty text message. |
To test, send a first message, then continue with a second message using the returned ID. Check that the same conversation is recorded in Inbox. Deleting the API connection invalidates its key for subsequent requests.