> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Agents

> Turn chat agents on or off and have one start a conversation on SMS or WhatsApp.

## Overview

A **chat agent** answers your customers in writing, on SMS, WhatsApp and email. You build and tune it in the Sendora app: its instructions, knowledge, tools and channels. The API lets you see your chat agents, turn them on or off, and have one write first to a contact. They use the same agent endpoints as voice agents: **List or get agents** (`type=chat`), **Update agent** (`live`) and **Send a message or start a chat** (`chat_agent_id`).

Chat agents are switched on per workspace. Until they are on for yours, every chat agent endpoint answers `404`.

The API never returns an agent's instructions, tools or any internal identifier. Each agent has a public `id`, the same value you see in the app address bar.

## Listing and reading agents

```bash theme={"dark"}
curl "https://api.sendora.ai/api/v1/public/agents?type=chat&page=1&per_page=50" \
  -H "X-API-Key: sk_live_..."
```

Returns an array, newest first. `X-Total-Count`, `X-Page` and `X-Per-Page` report where you are in the list. See [Pagination](https://docs.sendora.ai/concepts/pagination.md).

```json theme={"dark"}
[
  {
    "id": "l7EsEhjBq3ct7Xc4C4dAvA",
    "name": "Front desk",
    "live": true,
    "conversations_7d": 12,
    "channels": [
      { "channel": "whatsapp", "enabled": true, "connected": true, "mode": "auto" },
      { "channel": "sms", "enabled": false, "connected": false, "mode": "auto" },
      { "channel": "email", "enabled": false, "connected": false, "mode": "draft" }
    ]
  }
]
```

* `connected` means a number or mailbox is assigned to the agent for that channel.
* `enabled` means the agent is answering on it now.
* `mode` is `auto` when the agent replies right away and `draft` when it writes a draft for a person to approve.

Read one agent with `GET /api/v1/public/agents?id={agent_id}`.

## Turning an agent on or off

```bash theme={"dark"}
curl -X PATCH "https://api.sendora.ai/api/v1/public/agents/{agent_id}" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "live": true }'
```

Turning on switches the agent on for every channel that has an account connected, and the response lists `channels_on` and `channels_missing`. It needs at least one connected channel (`422` otherwise). If a channel's account already belongs to another agent the call answers `409`. Turning off stops the agent on every channel.

## Starting a chat

The agent writes first. It sends an opening message on SMS or WhatsApp and then carries the conversation, with its own instructions, knowledge and tools.

```bash theme={"dark"}
curl -X POST "https://api.sendora.ai/api/v1/public/messages" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chat_agent_id": "{agent_id}",
    "channel": "whatsapp",
    "phone": "+15551234567",
    "opening": "Hi Sam, it is Maya from Bright Smiles. Do you want a Saturday checkup slot?"
  }'
```

Give `phone` (with country code) or `lead_id`, not neither. Leave `opening` out and the agent writes the first message from its instructions. The response returns the text that was sent.

A chat is refused when:

| Status | Reason |
| - | - |
| `409` | The contact opted out of messages. |
| `409` | It is outside 8 AM to 9 PM for the contact. |
| `409` | The agent is not switched on for that channel. |
| `409` | A chat with the same person was started in the last minute. |
| `409` | The contact is in a running campaign. Its replies follow that campaign. |
| `409` | The agent is in test mode and the number is not on its allowed list. |
| `422` | No `phone` or `lead_id`, or the number has no country code. |
| `429` | The agent reached its sending limit. Try later. |
| `403` | The workspace is restricted for trust and safety reasons. |

Starting a chat sends a real message and uses the workspace's messaging balance.

## In a campaign

A chat agent can answer a campaign's replies on email, SMS and WhatsApp. Set the campaign's `reply_mode` and `reply_agent_id`, see [Answering replies](https://docs.sendora.ai/guides/campaigns.md).

An SMS or WhatsApp step can also let a chat agent write its opening message. In the step's configuration set `chat_agent_id` to the agent's `id`:

* Leave the step's message empty and the agent writes the opening from its instructions, for each lead, when the step runs.
* Write a message and it is sent as written.

Everything else about the step stays the same: send windows, sender rotation, limits and timeline entries all apply. Launch checks warn when the campaign's replies are off or go to a different agent, and block a step whose chat agent cannot be found.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.