> For the complete documentation index, see [llms.txt](https://docs.athenachat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.athenachat.ai/api-reference/en/endpoints/messages.md).

# Messages

Send customer messages and your team's replies to an API channel, with or without files

## Send a message to the API channel

`POST /chats/chat/send-message-universal`

Adds a message to a chat of your [API channel](/api-reference/en/guides/api-channel.md):

* `role: user` — a message from your customer. The AI agent answers it, and the reply arrives at your [webhook](/api-reference/en/guides/webhooks.md#new_messages).
* `role: assistant` — a reply your team already sent in your own system. It's saved to the chat history and used by the agent as context, but isn't sent anywhere.

If the chat with this `externalChatId` doesn't exist yet, Athena creates it.

### Body parameters

Send the parameters as JSON, or as `multipart/form-data` when you attach files.

| Parameter        | Type   | Required | Description                                                                                                           |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `channel`        | string | Yes      | Always `custom`                                                                                                       |
| `channelId`      | string | Yes      | ID of your API channel, from the **Webhook** tab of the channel settings. Starts with `cc:`                           |
| `externalChatId` | string | Yes      | Your identifier of the conversation. Messages with the same value go to the same chat                                 |
| `role`           | string | Yes      | `user` — the customer; `assistant` — your team                                                                        |
| `text`           | string | Yes      | Message text. Required even when you attach files                                                                     |
| `senderName`     | string | No       | Customer's name. It becomes the chat name in the **Inbox**. Default: `Unknown visitor`                                |
| `messageId`      | string | No       | Your ID of the message. A repeated message with the same `messageId` in the same chat is ignored, so retries are safe |
| `files`          | file   | No       | Attachments, only with `multipart/form-data`: up to 10 files, 10 MB each                                              |

### Request

{% tabs %}
{% tab title="JSON" %}

```bash
curl -X POST "https://hub.athenachat.ai/api/v1/chats/chat/send-message-universal" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "custom",
    "channelId": "cc:V1StGXR8_Z5jdHi6B-myT",
    "externalChatId": "customer-1042",
    "senderName": "Emma Clark",
    "role": "user",
    "text": "Hi! Do you deliver on Saturdays?",
    "messageId": "msg-88231"
  }'
```

{% endtab %}

{% tab title="With files" %}

```bash
curl -X POST "https://hub.athenachat.ai/api/v1/chats/chat/send-message-universal" \
  -H "Authorization: YOUR_API_KEY" \
  -F "channel=custom" \
  -F "channelId=cc:V1StGXR8_Z5jdHi6B-myT" \
  -F "externalChatId=customer-1042" \
  -F "senderName=Emma Clark" \
  -F "role=user" \
  -F "text=Here is a photo of the damaged box" \
  -F "files=@box.jpg"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  "https://hub.athenachat.ai/api/v1/chats/chat/send-message-universal",
  {
    method: "POST",
    headers: {
      Authorization: process.env.ATHENA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      channel: "custom",
      channelId: "cc:V1StGXR8_Z5jdHi6B-myT",
      externalChatId: "customer-1042",
      senderName: "Emma Clark",
      role: "user",
      text: "Hi! Do you deliver on Saturdays?",
      messageId: "msg-88231",
    }),
  },
);

if (!response.ok) {
  throw new Error(`Athena API error: ${response.status}`);
}
```

{% endtab %}
{% endtabs %}

### Response

`201 Created` with an empty body.

`201` means Athena accepted the request. The AI agent doesn't answer when:

* the channel or the agent is turned off, or **Disable agent responses** is on;
* it's outside the agent's working hours — the auto-reply is sent instead, if you set one up;
* the chat is paused;
* the message repeats an earlier `messageId`.

{% hint style="warning" %}
If `channelId` doesn't match any of your API channels, the message is ignored, but you still get `201`. When you set up the integration, check that the first messages appear in the **Inbox**.
{% endhint %}

### Files

| Type   | Formats              | What happens                                         |
| ------ | -------------------- | ---------------------------------------------------- |
| Images | JPEG, PNG, GIF, WebP | Saved to the chat; the agent takes them into account |
| Audio  | MP3, WAV             | Processed as a voice message                         |

The endpoint also accepts PDF, TXT, DOC, DOCX, XLS, XLSX, MP4 and AVI files, but the agent doesn't process them yet. Other file types are rejected.

### Errors

| Status | When                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------- |
| `400`  | A required parameter is missing, `role` or `channel` is invalid, or an unknown parameter was sent |
| `400`  | `uniqueId` was sent — it isn't used for the API channel                                           |
| `400`  | More than 10 files were attached                                                                  |
| `413`  | A file is larger than 10 MB                                                                       |

See [Errors and limits](/api-reference/en/errors-and-limits.md) for the other errors.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.athenachat.ai/api-reference/en/endpoints/messages.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.