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 |
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
Returns the initial AI Employee greeting and conversation metadata.
| Field | Type | Description |
|---|
conversation_id | string | UUID of the created conversation |
messages | array | Initial messages (e.g., welcome message) |
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 | string | Yes | The user's message text |
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": "How do I reset my password?"
}'
Response
Returns the AI Employee's reply, including message content, snippets, and sources.
| Field | Type | Description |
|---|
messages | array | AI response messages with snippets and sources |
RespondToMessage (Asynchronous)
Send a user message without waiting for the AI response.
| 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
| Field | Type | Required | Description |
|---|
message | string | Yes | The user's message text |
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": "Generate a summary report for Q4 sales"
}'
The response acknowledges receipt. Poll GetMessages to retrieve the AI response 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
Returns the full message history for the conversation, including all messages and conversation metadata.
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.
GetConversationFeedback
Retrieve aggregated feedback for conversations.
| Property | Value |
|---|
| URL | /api/conversations/get_conversation_feedback |
| HTTP Method | GET |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Query Parameters
| Parameter | Type | Required | Description |
|---|
persona_id | string | Yes | UUID of the AI Employee |
Example
curl -X GET "https://your-instance.ema.co/api/conversations/get_conversation_feedback?persona_id=<persona_id>" \
-H "Authorization: Bearer <access_token>"
GetConversationFeedbackDetail
Retrieve detailed feedback for a specific conversation.
| Property | Value |
|---|
| URL | /api/conversations/get_conversation_feedback_detail |
| HTTP Method | GET |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Query Parameters
| Parameter | Type | Required | Description |
|---|
conversation_id | string | Yes | UUID of the conversation |
Example
curl -X GET "https://your-instance.ema.co/api/conversations/get_conversation_feedback_detail?conversation_id=<conversation_id>" \
-H "Authorization: Bearer <access_token>"
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 |
event_data | object | No | Additional event data |