> Source: https://builder-docs.ema.ai/api-reference/chat/chat-api
> Title: Chat API

# 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)

### Headers

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

```bash
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)

### Headers

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

```bash
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)

### Headers

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

```bash
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)

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

### Path Parameters

Parameter

Type

Description

`conversation_id`

string

UUID of the conversation

### Example

```bash
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)

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

### Path Parameters

Parameter

Type

Description

`persona_id`

string

UUID of the AI Employee

### Example

```bash
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)

### Headers

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

```bash
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)

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

### Query Parameters

Parameter

Type

Required

Description

`conversation_id`

string

Yes

UUID of the conversation

### Example

```bash
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)

### Headers

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

## Related

-   [Chat Overview](/legacy-docs/api-reference/chat/overview) -- Concepts and architecture
-   [Chat Data Model](/legacy-docs/api-reference/chat/data-model) -- Message structures
-   [AI Employee API](/legacy-docs/api-reference/ai-employees/ai-employee-api) -- AI Employee management