---
title: "Send a live chat message"
method: POST
path: "/live-chat"
tags: ["Chatbot Operations"]
---

# Send a live chat message

`POST /live-chat`

## Request

- Base URL: `https://api.chat-data.com/api/v2`
- URL: `https://api.chat-data.com/api/v2/live-chat`
- Auth: HTTP bearer

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

- object
  - `chatbotId` string, required: The unique identifier of the chatbot.
  - `message` string, required: 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, required: The unique identifier of the conversation. It must be an existing conversation of the chatbot.
  - `role` 'human' | 'assistant' | 'user': 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: 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, uri: 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` object[]: An optional array of file objects to be attached to the message, at most 3.
    - `name` string, required: The name of the file.
    - `type` string, required: The MIME type of the file (for example `image/png` or `application/pdf`).
    - `url` string, uri, required: The public URL of the file that is hosted by you.

## Response `200`

Successful response.

- object
  - `status` 'success', required
  - `emailed_offline_message` boolean, required: Whether the message was also emailed to the user because they were offline. This only happens when the role is 'human' and the conversation's lead has an email address.
  - `is_user_online` boolean, required: Whether the user is currently online in the conversation.
  - `delivery` object: Only present when the conversation came from WhatsApp, WhatsApp Web, Instagram, Messenger, Telegram or LINE and `role` is `human` or `assistant`. The message is stored either way; this tells whether it was handed to the platform.
    - `channel` string, required: The platform of the conversation (its `source`).
    - `state` 'accepted' | 'skipped' | 'failed', required: `accepted`: the message was handed to the platform (this does not confirm delivery). `skipped`: not sent because the user's last message is more than 24 hours old (send a template message instead). `failed`: the send failed.
    - `reason` 'outside_24h_window' | 'send_failed' | 'send_error': Why the message was skipped or failed. Absent when `state` is `accepted`.
    - `error` string, nullable: The platform's error message, when there is one. Absent when `state` is `accepted`.

## Other responses

- `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.

---

[API](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide.md) · [All operations](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/llms.txt) · [OpenAPI document](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/revisions/72871007f7f0?raw)