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

# Overview

> RyzeAPI's native Chatwoot integration: activation, status, and deactivation

RyzeAPI integrates natively with [Chatwoot](https://www.chatwoot.com/). When you activate it, RyzeAPI creates an inbox in Chatwoot and keeps the realtime connection: messages received on WhatsApp show up in Chatwoot, and the agent's replies in Chatwoot flow back to WhatsApp.

<Info>
  When the Chatwoot module is not enabled on the server, **all module endpoints return `503`** with the message `integration gateway not configured`.
</Info>

## How it works

1. You activate the integration with `POST /api/chatwoot/set/:instance` (or inline, when creating the instance).
2. RyzeAPI creates the inbox in Chatwoot and starts delivering the WhatsApp messages it receives there.
3. The replies sent by the agent in Chatwoot flow back to RyzeAPI and are delivered to WhatsApp.

## Management endpoints

<CardGroup cols={3}>
  <Card title="Activate" icon="plug" href="/en/api/chatwoot/activate">
    `POST /api/chatwoot/set/:instance`, provisions the integration and creates the inbox.
  </Card>

  <Card title="Status / Info" icon="circle-info" href="/en/api/chatwoot/info">
    `GET /api/chatwoot/list/:instance`, returns the current state of the integration.
  </Card>

  <Card title="Deactivate" icon="power-off" href="/en/api/chatwoot/deactivate">
    `DELETE /api/chatwoot/delete/:instance`, removes the integration (the Chatwoot inbox is preserved).
  </Card>
</CardGroup>

## Inline activation when creating the instance

The integration can be activated **together with instance creation**, without a separate `set` call. Just include the `chatwoot*` block in the body of [`POST /api/instance/new`](/en/api/instance/create):

```json theme={null}
{
  "name": "suporte",
  "chatwootEnabled": true,
  "chatwootBaseUrl": "https://chatwoot.example.com",
  "chatwootAccountId": 5,
  "chatwootApiToken": "sk_live_abc123...",
  "chatwootInboxName": "WhatsApp - Orion"
}
```

If activation fails (wrong token or unreachable host), the instance **is still created**, the `chatwoot` object comes back with `status: "error"` and `error: "<message>"`. You can then call [`POST /api/chatwoot/set/:instance`](/en/api/chatwoot/activate) to fix the credentials without recreating the instance.

## Detect whether the module is enabled

```bash theme={null}
curl -s -o /dev/null -w "%{http_code}\n" \
  "https://ryzeapi.cloud/api/chatwoot/list/anything" \
  -H "token: $Token_Account"

# 503 → Chatwoot module not enabled on the server
# 404 → module enabled, but instance/integration does not exist
# 200 → module enabled and integration configured
```

## Data model

The server persists each integration in the `chatwoot_integrations` table. The `chatwootApiToken` is encrypted at rest with **AES-256-GCM** and is returned in plaintext by [`GET /api/chatwoot/list/:instance`](/en/api/chatwoot/info).

| Field                                       | Description                              |
| ------------------------------------------- | ---------------------------------------- |
| `bridge_integration_id`                     | Internal integration ID.                 |
| `chatwoot_base_url`                         | URL of the Chatwoot installation.        |
| `chatwoot_account_id`                       | Numeric ID of the Chatwoot account.      |
| `chatwoot_inbox_id` / `chatwoot_inbox_name` | Inbox created in Chatwoot.               |
| `status`                                    | `active` / `paused` / `error`.           |
| `last_error`                                | Last error message from the integration. |

## Next steps

<CardGroup cols={2}>
  <Card title="Activate integration" icon="plug" href="/en/api/chatwoot/activate">
    Provision the integration with `POST /api/chatwoot/set/:instance`.
  </Card>

  <Card title="Chatwoot errors" icon="triangle-exclamation" href="/en/guide/errors">
    Mapping table of the integration's HTTP status codes and messages.
  </Card>
</CardGroup>