# Simplidy API v1

Read and reply to your business's official WhatsApp conversations over HTTP, get webhook notifications or connect an AI agent through MCP. All in JSON.

- Base URL: `https://api.simplidy.com/v1`
- Documentation: https://app.simplidy.com/docs/api/v1
- Dates in ISO 8601 (UTC). Bodies and responses in JSON (UTF-8).

## Authentication

Create a token in Settings > API & MCP and send it on every call. "read" reads; "write" can also reply and change conversations. What you send shows in the chat with the token's name.

```
Authorization: Bearer SEU_TOKEN
Accept: application/json
Content-Type: application/json
```

## Versioning

The version is in the path (/v1, /v2...) and each one works separately: integrations on one version are not affected when another ships. Every response includes the X-Simplidy-Api-Version header. Use the selector at the top to see the docs for each version.
- Within v1 only backward-compatible changes ship: new fields and endpoints, never removals or changed meanings.
- Ignore fields you don't recognize: they may appear at any time.

## How to attend (for AI agents)

1. List the queue: GET /conversations?filter=agent.
2. Open each conversation (GET /conversations/{id}) and read the messages, notes and knowledge base.
3. Reply with POST /conversations/{id}/messages if window_open is true; otherwise, use an approved template.
4. Don't reply to conversations with taken_over_by set: a team member took over.
5. Only use facts from the knowledge base. If the answer isn't there, add the "Precisa de humano" tag.
6. When the matter is done, mark it resolved (PATCH with resolved=true).

## Objects

### Conversation

| Field | Type | Description |
|---|---|---|
| `id` | string (uuid) | Conversation identifier. It is the {id} in the paths. |
| `name` | string | Saved name or WhatsApp profile name. |
| `phone` | string | Phone in international format (+55...). |
| `account` | object | Business WhatsApp number that received the conversation (id and name). |
| `last_message` | string|null | Preview of the last message. |
| `last_message_at` | string (ISO 8601, UTC) | Date of the last message. |
| `waiting_reply` | boolean | The last message is from the contact and the conversation is not resolved. |
| `unread` | integer | Messages not read by the team. |
| `window_open` | boolean | 24-hour window open: free text can be sent. |
| `window_closes_at` | string|null | When the 24-hour window closes. |
| `taken_over_by` | string|null | Name of the person who took over. When set, the agent must not reply. |
| `resolved` | boolean | Conversation resolved. |
| `tags` | string[] | Tags. |
| `notes` | string|null | Internal notes about the contact. |

### Message

| Field | Type | Description |
|---|---|---|
| `id` | integer | Message identifier (use in reply_to_message_id and before_id). |
| `from` | contact | business | Who sent it. |
| `by` | string | Business messages only: person, token name (agent), "IA de reserva · model" or "celular" (phone). |
| `type` | string | text, image, video, audio, document, sticker, location, template... |
| `text` | string | Text or caption. |
| `media` | string | File name, when there is media. |
| `template` | string | Template name, when a template was sent. |
| `reply_to` | object | Quoted message (id and text). |
| `status` | string | Business messages only: pending, sent, delivered, read or failed. |
| `sent_at` | string (ISO 8601, UTC) | Sent date. |

### Knowledge base item

| Field | Type | Description |
|---|---|---|
| `id` | integer | Item identifier. |
| `account_id` | integer|null | Number the item belongs to; null applies to all. |
| `title` | string | Title. |
| `content` | string | Text with the information. |
| `images` | object[] | Item photos (index and name). Send with knowledge-image. |

## Endpoints

### Reading (read permission)

#### Who am I: `GET /v1/me`

Who owns the token and its permissions.

**Example**

```bash
curl "https://api.simplidy.com/v1/me" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"
```

**Response 200**

```json
{
    "user": {
        "name": "Micaias",
        "email": "voce@empresa.com"
    },
    "token": {
        "name": "Claude",
        "abilities": [
            "read",
            "write"
        ]
    }
}
```

#### Connected numbers: `GET /v1/accounts`

Connected WhatsApp numbers.

**Example**

```bash
curl "https://api.simplidy.com/v1/accounts" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"
```

**Response 200**

```json
{
    "accounts": [
        {
            "id": 1,
            "name": "Atendimento",
            "display_phone": "+55 11 98765-0000",
            "status": "connected"
        }
    ]
}
```

#### List conversations: `GET /v1/conversations`

Conversations from newest to oldest. Without a filter, returns the agent queue.

**Query parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `filter` | string | no | agent (default: waiting for a reply and not taken over), awaiting, unread, human, resolved, expiring (window closes in under 2 h) or all. |
| `account_id` | integer | no | Only conversations of this number. |
| `tag` | string | no | Only conversations with this tag. |
| `search` | string | no | Search by name or phone. |
| `limit` | integer | no | 1 to 100 (default 30). |

**Example**

```bash
curl "https://api.simplidy.com/v1/conversations?filter=agent&limit=20" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"
```

**Response 200**

```json
{
    "conversations": [
        {
            "id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
            "name": "Maria Souza",
            "phone": "+5511987650001",
            "account": {
                "id": 1,
                "name": "Atendimento"
            },
            "last_message": "Que horas vocês abrem amanhã?",
            "last_message_at": "2026-11-19T14:02:11+00:00",
            "waiting_reply": true,
            "unread": 1,
            "window_open": true,
            "window_closes_at": "2026-11-20T14:02:11+00:00",
            "taken_over_by": null,
            "resolved": false,
            "tags": [
                "Orçamento"
            ],
            "notes": "Prefere contato de manhã"
        }
    ]
}
```

#### Open conversation: `GET /v1/conversations/{id}`

Conversation with notes, tags, 24-hour window, latest messages and the number's knowledge base.

**Query parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | no | How many messages to return (default 40, max 100). |

**Example**

```bash
curl "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"
```

**Response 200**

```json
{
    "conversation": {
        "id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
        "name": "Maria Souza",
        "phone": "+5511987650001",
        "account": {
            "id": 1,
            "name": "Atendimento"
        },
        "last_message": "Que horas vocês abrem amanhã?",
        "last_message_at": "2026-11-19T14:02:11+00:00",
        "waiting_reply": true,
        "unread": 1,
        "window_open": true,
        "window_closes_at": "2026-11-20T14:02:11+00:00",
        "taken_over_by": null,
        "resolved": false,
        "tags": [
            "Orçamento"
        ],
        "notes": "Prefere contato de manhã"
    },
    "messages": [
        {
            "id": 812,
            "from": "contact",
            "type": "text",
            "text": "Que horas vocês abrem amanhã?",
            "sent_at": "2026-11-19T14:02:11+00:00"
        }
    ],
    "knowledge": [
        {
            "id": 7,
            "account_id": null,
            "title": "Horário de funcionamento",
            "content": "Segunda a sexta, das 9h às 18h. Sábado, das 9h às 13h.",
            "images": [
                {
                    "index": 0,
                    "name": "fachada.jpg"
                }
            ]
        }
    ]
}
```

#### Messages: `GET /v1/conversations/{id}/messages`

Messages in chronological order. To fetch older ones, pass in before_id the id of the first one you already have.

**Query parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | no | How many messages to return (default 40, max 100). |
| `before_id` | integer | no | Only messages before this one. |

**Example**

```bash
curl "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d/messages?limit=40&before_id=800" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"
```

**Response 200**

```json
{
    "messages": [
        {
            "id": 812,
            "from": "contact",
            "type": "text",
            "text": "Que horas vocês abrem amanhã?",
            "sent_at": "2026-11-19T14:02:11+00:00"
        },
        {
            "id": 813,
            "from": "business",
            "by": "Claude",
            "type": "text",
            "text": "Olá, Maria! Abrimos às 9h.",
            "reply_to": {
                "id": 812,
                "text": "Que horas vocês abrem amanhã?"
            },
            "status": "sent",
            "sent_at": "2026-11-19T14:03:40+00:00"
        }
    ]
}
```

#### Approved templates: `GET /v1/accounts/{id}/templates`

Approved templates of the number (name, language, text, variables). supported=false: the template has a media or variable header and can't be sent through the API.

**Example**

```bash
curl "https://api.simplidy.com/v1/accounts/1/templates" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"
```

**Response 200**

```json
{
    "templates": [
        {
            "name": "order_update",
            "language": "pt_BR",
            "category": "UTILITY",
            "body": "Olá {{1}}, seu pedido {{2}} saiu para entrega.",
            "variables": 2,
            "supported": true
        }
    ],
    "error": null
}
```

#### Knowledge base: `GET /v1/knowledge`

Active knowledge base (general and per number), with each item's photos.

**Query parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `account_id` | integer | no | Includes this number's items besides the general ones. |

**Example**

```bash
curl "https://api.simplidy.com/v1/knowledge" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"
```

**Response 200**

```json
{
    "knowledge": [
        {
            "id": 7,
            "account_id": null,
            "title": "Horário de funcionamento",
            "content": "Segunda a sexta, das 9h às 18h. Sábado, das 9h às 13h.",
            "images": [
                {
                    "index": 0,
                    "name": "fachada.jpg"
                }
            ]
        }
    ]
}
```

### Sending and handling (write permission)

#### Reply with text: `POST /v1/conversations/{id}/messages`

Replies with text. Only works with the 24-hour window open (window_open); outside it, use a template.

**Body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | yes | Reply text (up to 4096 characters). |
| `reply_to_message_id` | integer | no | Id of the message to quote. |

**Example**

```bash
curl -X POST "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"text":"Olá, Maria! Abrimos às 9h.","reply_to_message_id":812}'
```

**Response 201**

```json
{
    "message": {
        "id": 813,
        "from": "business",
        "by": "Claude",
        "type": "text",
        "text": "Olá, Maria! Abrimos às 9h.",
        "reply_to": {
            "id": 812,
            "text": "Que horas vocês abrem amanhã?"
        },
        "status": "sent",
        "sent_at": "2026-11-19T14:03:40+00:00"
    }
}
```

#### Send template: `POST /v1/conversations/{id}/template`

Sends an approved template (works outside the window).

**Body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Template name. |
| `language` | string | yes | Template language, e.g. pt_BR. |
| `params` | string[] | no | Values for variables {{1}}, {{2}}..., in order. |

**Example**

```bash
curl -X POST "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d/template" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"order_update","language":"pt_BR","params":["Maria","#2381"]}'
```

**Response 201**

```json
{
    "message": {
        "id": 814,
        "from": "business",
        "by": "Claude",
        "type": "template",
        "text": "Olá Maria, seu pedido #2381 saiu para entrega.",
        "reply_to": null,
        "status": "sent",
        "sent_at": "2026-11-19T14:03:40+00:00",
        "template": "order_update"
    }
}
```

#### Send knowledge photo: `POST /v1/conversations/{id}/knowledge-image`

Sends the contact a photo from a knowledge base item.

**Body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `knowledge_id` | integer | yes | Knowledge item id. |
| `image_index` | integer | no | Photo index in the item (default 0). |
| `caption` | string | no | Caption. |

**Example**

```bash
curl -X POST "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d/knowledge-image" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_id":7,"image_index":0,"caption":"Nossa fachada"}'
```

**Response 201**

```json
{
    "message": {
        "id": 815,
        "from": "business",
        "by": "Claude",
        "type": "image",
        "text": "Nossa fachada",
        "reply_to": null,
        "status": "sent",
        "sent_at": "2026-11-19T14:03:40+00:00",
        "media": "fachada.jpg"
    }
}
```

#### Update handling: `PATCH /v1/conversations/{id}`

Updates handling: notes, resolve, take over, tags. Send only the fields you want to change.

**Body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `notes` | string|null | no | Replaces the notes (read first so nothing is lost). |
| `resolved` | boolean | no | true resolves; false reopens. |
| `takeover` | boolean | no | true: the token owner takes over and the agent stops; false: hands back to the agent. |
| `add_tags` | string[] | no | Tags to add (created if they don't exist). |
| `remove_tags` | string[] | no | Tags to remove. |

**Example**

```bash
curl -X PATCH "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"resolved":true,"notes":"Prefere contato de manhã. Agendou para sexta.","add_tags":["Agendou"],"remove_tags":["Precisa de humano"]}'
```

**Response 200**

```json
{
    "conversation": {
        "id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
        "name": "Maria Souza",
        "phone": "+5511987650001",
        "account": {
            "id": 1,
            "name": "Atendimento"
        },
        "last_message": "Que horas vocês abrem amanhã?",
        "last_message_at": "2026-11-19T14:02:11+00:00",
        "waiting_reply": false,
        "unread": 1,
        "window_open": true,
        "window_closes_at": "2026-11-20T14:02:11+00:00",
        "taken_over_by": null,
        "resolved": true,
        "tags": [
            "Orçamento",
            "Agendou"
        ],
        "notes": "Prefere contato de manhã. Agendou para sexta."
    }
}
```

#### Create knowledge item: `POST /v1/knowledge`

Creates a knowledge item (requires "Fill with AI" on). If review is on, the item starts disabled (enabled=false) until someone approves it.

**Body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | string | yes | Title (up to 150 characters). |
| `content` | string | yes | Text (up to 5000 characters). |
| `account_id` | integer|null | no | Number the item belongs to; empty applies to all. |

**Example**

```bash
curl -X POST "https://api.simplidy.com/v1/knowledge" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title":"Horário de funcionamento","content":"Segunda a sexta, das 9h às 18h.","account_id":null}'
```

**Response 201**

```json
{
    "knowledge": {
        "id": 7,
        "account_id": null,
        "title": "Horário de funcionamento",
        "content": "Segunda a sexta, das 9h às 18h.",
        "images": []
    },
    "enabled": true
}
```

#### Update knowledge item: `PUT /v1/knowledge/{id}`

Updates a knowledge base item.

**Body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | string | yes | Title (up to 150 characters). |
| `content` | string | yes | Text (up to 5000 characters). |
| `account_id` | integer|null | no | Number the item belongs to; empty applies to all. |

**Example**

```bash
curl -X PUT "https://api.simplidy.com/v1/knowledge/7" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title":"Horário de funcionamento","content":"Segunda a sábado, das 9h às 18h."}'
```

**Response 200**

```json
{
    "knowledge": {
        "id": 7,
        "account_id": null,
        "title": "Horário de funcionamento",
        "content": "Segunda a sábado, das 9h às 18h.",
        "images": [
            {
                "index": 0,
                "name": "fachada.jpg"
            }
        ]
    },
    "enabled": true
}
```

#### Delete knowledge item: `DELETE /v1/knowledge/{id}`

Deletes a knowledge base item.

**Example**

```bash
curl -X DELETE "https://api.simplidy.com/v1/knowledge/7" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"
```

**Response 200**

```json
{
    "deleted": 7
}
```

## Webhooks

Register in Settings > Webhooks. Each notification is a JSON POST signed with the webhook secret.

```
X-Simplidy-Event: message.received
X-Simplidy-Api-Version: 1
X-Simplidy-Delivery: <uuid>
X-Simplidy-Signature: sha256=<hmac_sha256(corpo, segredo)>
```

Verify the signature and reply with HTTP 2xx within 5 seconds. After 20 failures in a row the webhook is paused.

```php
$ok = hash_equals('sha256='.hash_hmac('sha256', $corpo, $segredo), $_SERVER['HTTP_X_SIMPLIDY_SIGNATURE']);
```

### `message.received`

Message received from the contact

```json
{
    "id": "6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f",
    "event": "message.received",
    "created_at": "2026-11-19T14:02:12+00:00",
    "data": {
        "conversation": {
            "id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
            "name": "Maria Souza",
            "phone": "+5511987650001",
            "account": {
                "id": 1,
                "name": "Atendimento"
            },
            "last_message": "Que horas vocês abrem amanhã?",
            "last_message_at": "2026-11-19T14:02:11+00:00",
            "waiting_reply": true,
            "unread": 1,
            "window_open": true,
            "window_closes_at": "2026-11-20T14:02:11+00:00",
            "taken_over_by": null,
            "resolved": false,
            "tags": [
                "Orçamento"
            ],
            "notes": "Prefere contato de manhã"
        },
        "message": {
            "id": 812,
            "from": "contact",
            "type": "text",
            "text": "Que horas vocês abrem amanhã?",
            "sent_at": "2026-11-19T14:02:11+00:00"
        }
    }
}
```

### `message.sent`

Message sent (team, agent or phone)

```json
{
    "id": "6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f",
    "event": "message.sent",
    "created_at": "2026-11-19T14:02:12+00:00",
    "data": {
        "conversation": {
            "id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
            "name": "Maria Souza",
            "phone": "+5511987650001",
            "account": {
                "id": 1,
                "name": "Atendimento"
            },
            "last_message": "Olá, Maria! Abrimos às 9h.",
            "last_message_at": "2026-11-19T14:02:11+00:00",
            "waiting_reply": false,
            "unread": 0,
            "window_open": true,
            "window_closes_at": "2026-11-20T14:02:11+00:00",
            "taken_over_by": null,
            "resolved": false,
            "tags": [
                "Orçamento"
            ],
            "notes": "Prefere contato de manhã"
        },
        "message": {
            "id": 813,
            "from": "business",
            "by": "Claude",
            "type": "text",
            "text": "Olá, Maria! Abrimos às 9h.",
            "reply_to": {
                "id": 812,
                "text": "Que horas vocês abrem amanhã?"
            },
            "status": "sent",
            "sent_at": "2026-11-19T14:03:40+00:00"
        }
    }
}
```

### `message.status`

Message status (delivered, read, failed)

```json
{
    "id": "6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f",
    "event": "message.status",
    "created_at": "2026-11-19T14:02:12+00:00",
    "data": {
        "conversation": {
            "id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
            "name": "Maria Souza",
            "phone": "+5511987650001",
            "account": {
                "id": 1,
                "name": "Atendimento"
            },
            "last_message": "Que horas vocês abrem amanhã?",
            "last_message_at": "2026-11-19T14:02:11+00:00",
            "waiting_reply": false,
            "unread": 0,
            "window_open": true,
            "window_closes_at": "2026-11-20T14:02:11+00:00",
            "taken_over_by": null,
            "resolved": false,
            "tags": [
                "Orçamento"
            ],
            "notes": "Prefere contato de manhã"
        },
        "message": {
            "id": 813,
            "from": "business",
            "by": "Claude",
            "type": "text",
            "text": "Olá, Maria! Abrimos às 9h.",
            "reply_to": {
                "id": 812,
                "text": "Que horas vocês abrem amanhã?"
            },
            "status": "read",
            "sent_at": "2026-11-19T14:03:40+00:00"
        }
    }
}
```

### `conversation.event`

Conversation (take over, resolve, reopen, notes, tags, backup AI)

```json
{
    "id": "6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f",
    "event": "conversation.event",
    "created_at": "2026-11-19T14:02:12+00:00",
    "data": {
        "type": "resolved",
        "by": "Claude",
        "details": null,
        "conversation": {
            "id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
            "name": "Maria Souza",
            "phone": "+5511987650001",
            "account": {
                "id": 1,
                "name": "Atendimento"
            },
            "last_message": "Que horas vocês abrem amanhã?",
            "last_message_at": "2026-11-19T14:02:11+00:00",
            "waiting_reply": false,
            "unread": 1,
            "window_open": true,
            "window_closes_at": "2026-11-20T14:02:11+00:00",
            "taken_over_by": null,
            "resolved": true,
            "tags": [
                "Orçamento"
            ],
            "notes": "Prefere contato de manhã"
        }
    }
}
```

**conversation.event types (data.type)**

- `takeover`: Someone took over the conversation.
- `released`: Handed back to the agent.
- `resolved`: Resolved.
- `reopened`: Reopened.
- `reopened_by_contact`: Reopened because the contact wrote again.
- `notes`: Notes changed.
- `tag_added`: Tag added (details.tag).
- `tag_removed`: Tag removed (details.tag).
- `ai_replied`: The backup AI replied.
- `ai_failed`: The backup AI failed (details.error).

## MCP

For Claude, Codex or another agent: the MCP server provides the tools below, the "simplidy://guia" guide (how the CRM works) and the "attend-whatsapp" shortcut.

- With header: `https://api.simplidy.com/mcp` + `Authorization: Bearer SEU_TOKEN`
- Without header (claude.ai): `https://api.simplidy.com/mcp/t/SEU_TOKEN`

**Recommended: a Haiku subagent watching the queue**

To avoid spending the main model just checking for new messages, keep a subagent on Claude Haiku 5.5 (cheap and fast) calling list-conversations with filter "agent" every 1 or 2 minutes. When there is a conversation in the queue, it hands the id to the main agent, which reads and replies.

```
Subagente vigia (modelo: claude-haiku-5-5)
A cada 1 a 2 minutos, chame list-conversations com filter "agent" e limit 20.
- Fila vazia: não faça nada e espere a próxima rodada.
- Com conversas: devolva ao agente principal só os ids (uuid) e a última mensagem de cada uma.
Não responda clientes, não mude nada e não leia conversas inteiras: quem atende é o agente principal.
```

| Tool | Arguments (* required) | Description |
|---|---|---|
| `list-conversations` | filter, account_id, tag, search, limit | Conversation queue and search. |
| `get-conversation` | conversation_id*, limit | Full conversation with notes, tags and knowledge base. |
| `send-message` | conversation_id*, text*, reply_to_message_id | Replies with text. |
| `send-template` | conversation_id*, name*, language*, params | Sends an approved template. |
| `send-knowledge-image` | conversation_id*, knowledge_id*, image_index, caption | Sends a knowledge base photo. |
| `list-templates` | account_id* | A number's approved templates. |
| `update-conversation` | conversation_id*, notes, resolved, takeover, add_tags, remove_tags | Notes, resolve, take over and tags. |
| `get-knowledge` | account_id | Knowledge base. |
| `save-knowledge` | id, title*, content*, account_id | Saves a knowledge base item (with "Fill with AI" on). |
| `delete-knowledge` | id* | Deletes a knowledge base item. |
| `list-accounts` | — | Connected numbers. |

## Errors and limits

- `200 / 201`: Success (201 when something was created or sent).
- `401`: Missing, invalid or expired token.
- `403`: The token lacks the permission (read/write) or the feature is off.
- `404`: Conversation, item or number not found.
- `422`: Invalid data or Meta refused it (e.g. 24-hour window closed). The message explains why.
- `429`: Too many calls: up to 300 per minute per user, 60 sends per minute.
- `5xx`: Error on our side or Meta's. Try again in a few seconds.

**401**

```json
{
    "message": "Unauthenticated."
}
```

**422 (validation)**

```json
{
    "message": "The text field is required.",
    "errors": {
        "text": [
            "The text field is required."
        ]
    }
}
```

**422 (sending)**

```json
{
    "message": "A janela de 24 horas está fechada. Envie um modelo aprovado."
}
```
