# Send a live chat message

`POST https://api.chat-data.com/api/v2/live-chat`

Canonical: https://www.chat-data.com/api-reference/send-live-chat-message

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Send a live chat message to an existing conversation of a chatbot. The message can be sent as a human agent (`role: 'human'`), as an assistant response (`role: 'assistant'`) or as a user message (`role: 'user'`).

**Role behavior:**
- **'human' (default)**: The message is sent as a human agent. This automatically stops the AI bot so that it does not interfere with human assistance. The `name` and `avatar` parameters are used for the human agent's identity.
- **'assistant'**: The message is sent as an AI assistant response. The AI bot continues to operate normally. The `name` and `avatar` parameters are ignored.
- **'user'**: The message is sent as a user message. The AI bot continues to operate normally. The `name` and `avatar` parameters are ignored.

If you want to take over the conversation as a human agent, use the default 'human' role. If you want to send assistant responses without stopping the AI bot, use the 'assistant' role.

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotId | string | yes | The unique identifier of the chatbot. |
| message | string | yes | The message text to be sent to the conversation. It must be a non-empty string (an empty string gets a 400); to send only `files`, send a blank string such as a single space. |
| conversationId | string | yes | The unique identifier of the conversation. It must be an existing conversation of the chatbot. |
| role | string | no | The role of the message sender. Valid values: 'human' (human agent), 'assistant' (AI response) or 'user' (end user/customer). When the role is 'assistant' or 'user', the `name` and `avatar` parameters are ignored. |
| name | string | no | The name of the human agent sending the message. Only used when the role is 'human'. If unset, the workspace owner's name is used as the agent name. |
| avatar | string | no | The URL of the avatar image for the message sender. Only used when the role is 'human'. If unset, the workspace owner's avatar is used as the human agent's avatar. |
| files | array of object | no | An optional array of file objects to be attached to the message, at most 3. |
| files[].name | string | yes | The name of the file. |
| files[].type | string | yes | The MIME type of the file (for example `image/png` or `application/pdf`). |
| files[].url | string | yes | The public URL of the file that is hosted by you. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/live-chat' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "message": "Hi Jane, I'\''m Alex from the support team. Let me check your order status for you.",
  "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c"
}'
```

## Example response (200)

```json
{
  "status": "success",
  "emailed_offline_message": false,
  "is_user_online": true,
  "delivery": {
    "channel": "Whatsapp",
    "state": "accepted"
  }
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | The message could not be sent. For example: `chatbotId`, `conversationId` or `message` is missing or empty, `message` is not a string, `role` is not `human`, `assistant` or `user`, the plan does not include live chat, live chat is not enabled for the chatbot, the conversation does not exist, or `files` has more than 3 items or an invalid item. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |
| 503 | The request waited about 130 seconds behind earlier requests for the same conversation (`Server busy, please retry.`). Retry the request. |