Chat API
This page documents the API endpoints for managing chat conversations and messages with AI Employees.
CreateConversation
Create a new conversation with an AI Employee.
| Property | Value |
|---|
| URL | /api/chat/ |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
persona_id | string | Yes | UUID of the AI Employee to chat with |
user_context | object | No | Free-form context map merged into every message in the conversation |
caller | string | No | Identifier of the calling integration (for analytics) |
Example
curl -X POST https://your-instance.ema.co/api/chat/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"persona_id": "abc12345-6789-0abc-def0-123456789abc"
}'
Response
| Field | Type | Description |
|---|
conversation_id | string | UUID of the created conversation |
message | object | The opening ChatbotMessage (e.g. welcome message) |
snippets | array | Source snippets cited by the opening message, if any |
RespondToMessage (Synchronous)
Send a user message and receive an AI response synchronously.
| Property | Value |
|---|
| URL | /api/chat/{conversation_id} |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Path Parameters
| Parameter | Type | Description |
|---|
conversation_id | string | UUID of the conversation |
Request Body
| Field | Type | Required | Description |
|---|
message | object | Yes | A ChatbotMessage object (must include at least content). See Chat Data Model for the full shape. |
user_context | object | No | Per-message context merged with any conversation-level context |
original_message_id | string | No | ID of the original message when this is a retry / regeneration |
impersonation_request | object | No | For admin-impersonated calls |
Example
curl -X POST https://your-instance.ema.co/api/chat/<conversation_id> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"message": { "content": "How do I reset my password?" }
}'
Response
| Field | Type | Description |
|---|
conversation_id | string | UUID of the conversation |
message | object | The assistant's reply, as a ChatbotMessage |
snippets | array | Source snippets cited by the reply |
RespondToMessage (Asynchronous)
Send a user message without waiting for the AI response. Returns immediately with a placeholder message id; poll GetMessages to retrieve the assistant's reply when ready.
| Property | Value |
|---|
| URL | /api/chat/{conversation_id}/async |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Path Parameters
| Parameter | Type | Description |
|---|
conversation_id | string | UUID of the conversation |
Request Body
Same shape as RespondToMessage (Synchronous).
Example
curl -X POST https://your-instance.ema.co/api/chat/<conversation_id>/async \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"message": { "content": "Generate a summary report for Q4 sales" }
}'
Response
HTTP 202 with body:
| Field | Type | Description |
|---|
placeholder_message_id | string | ID of the placeholder message; use this with GetMessages to retrieve the assistant's reply when ready. |
GetMessages
Retrieve all messages in a conversation.
| Property | Value |
|---|
| URL | /api/chat/{conversation_id} |
| HTTP Method | GET |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Path Parameters
| Parameter | Type | Description |
|---|
conversation_id | string | UUID of the conversation |
Example
curl -X GET https://your-instance.ema.co/api/chat/<conversation_id> \
-H "Authorization: Bearer <access_token>"
Response
| Field | Type | Description |
|---|
messages | array | Array of ChatbotMessage objects, in chronological order |
GetChatbotConfig
Retrieve the chatbot configuration for a specific AI Employee.
| Property | Value |
|---|
| URL | /api/chat/config/{persona_id} |
| HTTP Method | GET |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Path Parameters
| Parameter | Type | Description |
|---|
persona_id | string | UUID of the AI Employee |
Example
curl -X GET https://your-instance.ema.co/api/chat/config/<persona_id> \
-H "Authorization: Bearer <access_token>"
Response
Returns the chatbot configuration including welcome message, suggested questions, branding, and display settings.
LogCustomEvent
Log a custom event for analytics tracking in a chatbot session.
| Property | Value |
|---|
| URL | /api/chat/events |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
event_name | string | Yes | Name of the custom event |
occurred_at | string (ISO-8601 datetime) | Yes | When the event occurred |
conversation_id | string | Yes | UUID of the conversation the event belongs to |
message_id | string | Yes | ID of the message the event references |
metadata | object | No | Additional event data |
Response
| Field | Type | Description |
|---|
success | boolean | true if the event was logged |