> ## 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.

# Visão Geral

> Integração nativa da RyzeAPI com Chatwoot: ativação, status e desativação

A RyzeAPI integra de forma nativa com o [Chatwoot](https://www.chatwoot.com/). Ao ativar, a RyzeAPI cria uma inbox no Chatwoot e mantém a conexão em tempo real: as mensagens recebidas no WhatsApp aparecem no Chatwoot, e as respostas do agente no Chatwoot voltam para o WhatsApp.

<Info>
  Quando o módulo Chatwoot não está habilitado no servidor, **todos os endpoints do módulo retornam `503`** com a mensagem `integration gateway not configured`.
</Info>

## Como funciona

1. Você ativa a integração com `POST /api/chatwoot/set/:instance` (ou inline, na criação da instância).
2. A RyzeAPI cria a inbox no Chatwoot e passa a entregar ali as mensagens recebidas no WhatsApp.
3. As respostas enviadas pelo agente no Chatwoot voltam para a RyzeAPI e são entregues no WhatsApp.

## Endpoints de gerenciamento

<CardGroup cols={3}>
  <Card title="Ativar" icon="plug" href="/pt/api/chatwoot/activate">
    `POST /api/chatwoot/set/:instance`, provisiona a integração e cria a inbox.
  </Card>

  <Card title="Status / Info" icon="circle-info" href="/pt/api/chatwoot/info">
    `GET /api/chatwoot/list/:instance`, retorna o estado atual da integração.
  </Card>

  <Card title="Desativar" icon="power-off" href="/pt/api/chatwoot/deactivate">
    `DELETE /api/chatwoot/delete/:instance`, remove a integração (a inbox no Chatwoot é preservada).
  </Card>
</CardGroup>

## Ativação inline na criação da instância

A integração pode ser ativada **junto com a criação da instância**, sem precisar chamar `set` separadamente. Basta enviar o bloco `chatwoot*` no body de [`POST /api/instance/new`](/pt/api/instance/create):

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

Se a ativação falhar (token errado ou host inacessível), a instância **continua sendo criada**, o objeto `chatwoot` retorna com `status: "error"` e `error: "<mensagem>"`. Você pode então chamar [`POST /api/chatwoot/set/:instance`](/pt/api/chatwoot/activate) para corrigir as credenciais sem recriar a instância.

## Detectar se o módulo está habilitado

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

# 503 → módulo Chatwoot não habilitado no servidor
# 404 → módulo habilitado, mas a instância/integração não existe
# 200 → módulo habilitado e integração configurada
```

## Modelo de dados

O servidor persiste cada integração na tabela `chatwoot_integrations`. O `chatwootApiToken` é encriptado at-rest com **AES-256-GCM** e é retornado em plaintext em [`GET /api/chatwoot/list/:instance`](/pt/api/chatwoot/info).

| Campo                                       | Descrição                              |
| ------------------------------------------- | -------------------------------------- |
| `bridge_integration_id`                     | ID interno da integração.              |
| `chatwoot_base_url`                         | URL da instalação Chatwoot.            |
| `chatwoot_account_id`                       | ID numérico da conta Chatwoot.         |
| `chatwoot_inbox_id` / `chatwoot_inbox_name` | Inbox criada no Chatwoot.              |
| `status`                                    | `active` / `paused` / `error`.         |
| `last_error`                                | Última mensagem de erro da integração. |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Ativar integração" icon="plug" href="/pt/api/chatwoot/activate">
    Provisione a integração com `POST /api/chatwoot/set/:instance`.
  </Card>

  <Card title="Erros do Chatwoot" icon="triangle-exclamation" href="/pt/guide/errors">
    Tabela de mapeamento dos status HTTP e mensagens da integração.
  </Card>
</CardGroup>