> 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/guides/api-channel.md).

# Connect your system via the API channel

Bring messages from your own app, website or contact center to an Athena AI agent

The **API channel** connects any messaging source that Athena doesn't support out of the box — your mobile app, your own website chat, a contact center or an internal tool. Your system forwards customer messages to Athena, the AI agent answers them, and Athena sends each reply to your webhook.

```
Your system ── customer message ──▶ POST /chats/chat/send-message-universal
                                               │
                                     AI agent processes it
                                               │
Your webhook ◀──── agent reply ─────  new_messages event (role: assistant)
```

***

## Step 1. Create an API channel

**Action:** In [your Athena account](https://app.athenachat.ai), open **Channels → Add channel**, select **API**, enter a channel name and click **Next**.

**Result:** the channel is created. Set up its AI agent — role, instructions, task, knowledge base — just like for any other channel.

## Step 2. Copy the channel ID and set the webhook URL

**Action:** Open the channel settings and go to the **Webhook** tab:

1. Copy the **Channel ID**. API channel IDs start with `cc:`, for example `cc:V1StGXR8_Z5jdHi6B-myT`.
2. In **Webhook URL**, enter the HTTPS address of your endpoint that will receive the agent's replies.
3. Click **Webhook test** — Athena sends a sample `new_messages` event to your URL.
4. Save the settings.

{% hint style="info" %}
Athena doesn't sign webhook requests. Protect your endpoint with a hard-to-guess URL, for example one that contains a secret token. See [Webhooks](/api-reference/en/guides/webhooks.md#secure-your-endpoint).
{% endhint %}

## Step 3. Send customer messages

Send every customer message to Athena with `role: user`. Use your own stable identifier of the conversation as `externalChatId` — all messages with the same `externalChatId` belong to one chat.

```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"
  }'
```

**Result:** `201 Created` with an empty body. The message appears in the **Inbox**, and the AI agent starts working on a reply.

See [Messages](/api-reference/en/endpoints/messages.md) for all parameters and for sending files.

## Step 4. Receive the agent's replies

When the agent replies, Athena sends a `new_messages` event to your webhook URL. Find the conversation by `chat.externalChatId` and show `messages[].text` to your customer:

```json
{
  "event": "new_messages",
  "chat": {
    "id": "5b0f6a2e-3d4c-4e8a-9a51-2f7c1b9d8e10",
    "name": "Emma Clark",
    "uniqueId": "cc:V1StGXR8_Z5jdHi6B-myT:customer-1042",
    "externalChatId": "customer-1042",
    "channelName": "custom"
  },
  "messages": [
    {
      "id": "e1c4a7b2-9f3d-4b6e-8c21-7a5d0f9e3b64",
      "role": "assistant",
      "senderName": "Athena AI",
      "attachments": [],
      "text": "Yes, we deliver on Saturdays from 10:00 to 16:00.",
      "createdAt": "2026-10-09T09:41:12.000Z"
    }
  ],
  "settings": {
    "behavior": "Be friendly and brief.",
    "role": "Customer support agent of a furniture store",
    "task": "Answer questions about delivery and take orders",
    "greeting": "Hello! How can I help?",
    "isActive": true,
    "aiLang": "en"
  },
  "timestamp": "2026-10-09T09:41:12.380Z"
}
```

Your webhook also receives the customer messages you sent in step 3 (`role: user`). Skip them if you don't need them.

See [Webhooks](/api-reference/en/guides/webhooks.md) for all events and fields.

***

## Messages from your team

If someone on your team answers the customer in your own system, you can record that reply in Athena with `role: assistant`. It's saved to the chat history, shown in the **Inbox** and used by the agent as conversation context. Athena doesn't send it anywhere and doesn't echo it to your webhook.

## Handle replies yourself

To stop the AI agent from answering in this channel, turn on **Disable agent responses** on the **Webhook** tab. Customer messages keep arriving at your webhook, and you answer them in your own system.

## Chat identifiers in the API channel

* `externalChatId` — your identifier of the conversation.
* `uniqueId` — Athena's chat key: `<channel ID>:<externalChatId>`, for example `cc:V1StGXR8_Z5jdHi6B-myT:customer-1042`.
* `id` — Athena's chat ID from `chat.id` in webhook events. Use it for [read and unread](/api-reference/en/endpoints/chats.md#mark-a-chat-as-read), [task status](/api-reference/en/endpoints/chats.md#mark-the-task-as-done) and [tags](/api-reference/en/endpoints/tags.md).

To block spam in the API channel, stop forwarding that customer's messages from your system.


---

# 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/guides/api-channel.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.