Pular para o conteúdo principal

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.

A integração com Chatwoot acontece por meio do microserviço RyzeIntegrations (bridge). A RyzeAPI não fala diretamente com o Chatwoot, toda comunicação passa pelo bridge, que cria a inbox no Chatwoot e mantém uma conexão WebSocket persistente com a RyzeAPI.
Quando o servidor está sem BRIDGE_URL ou BRIDGE_TOKEN configurados, todos os endpoints do módulo retornam 503 com a mensagem integration gateway not configured (set BRIDGE_URL and BRIDGE_TOKEN). Além disso, a rota interna /ws/chatwoot/:instance não é registrada (responde 404).

​
Como funciona

[ Cliente ] ──POST /api/chatwoot/set──► [ RyzeAPI ] ──POST /v1/integrations/activate──► [ RyzeIntegrations ]
                                                                                                  │
                                                                                                  ├─► cria inbox no Chatwoot
                                                                                                  └─► abre WS persistente
                                                                                                      em /ws/chatwoot/:instance
                                                                                                      (autenticado por BRIDGE_TOKEN)
A inbox criada pelo bridge passa a receber mensagens do WhatsApp via eventos da RyzeAPI. Mensagens enviadas pelo agente Chatwoot voltam para a RyzeAPI e são despachadas pelo whatsmeow.

​
Endpoints de gerenciamento

Ativar

POST /api/chatwoot/set/:instance, provisiona a integração (cria inbox + abre WS).

Status / Info

GET /api/chatwoot/list/:instance, leitura local enriquecida com dados live do bridge.

Desativar

DELETE /api/chatwoot/delete/:instance, remove a integração e apaga a inbox no Chatwoot.

​
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: 
{
  "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, host inacessível, bridge offline), 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 para corrigir as credenciais sem recriar a instância.

​
Variáveis de ambiente do servidor

Quem opera a plataforma precisa configurar estas variáveis para habilitar o módulo:
VariávelDescrição
BRIDGE_URLURL base do RyzeIntegrations (ex.: https://bridge.example.com).
BRIDGE_TOKENToken Bearer service-to-service.
BRIDGE_INTERNAL_RYZEAPI_URLURL que o bridge usa para chamar a RyzeAPI (útil em deploys container-to-container). Default: BASE_URL.

​
Detectar se o bridge está habilitado

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

# 503 → bridge não configurado no servidor
# 404 → bridge ativo, mas instância/integração não existe
# 200 → bridge ativo e integração configurada

​
Rota interna /ws/chatwoot/:instance

Esta rota é exclusiva do RyzeIntegrations bridge, autentica apenas via BRIDGE_TOKEN e não aceita TokenAccount nem TokenInstance. Ela existe num hub WebSocket separado do /ws/:instance público; backpressure de um lado não afeta o outro. Você não deve consumir essa rota diretamente.

​
Modelo de dados

O servidor persiste cada integração na tabela chatwoot_integrations. O chatwootApiToken é encriptado at-rest com AES-256-GCM e nunca é retornado pela API.
CampoDescrição
bridge_integration_idID retornado pelo RyzeIntegrations.
chatwoot_base_urlURL da instalação Chatwoot.
chatwoot_account_idID numérico da conta Chatwoot.
chatwoot_inbox_id / chatwoot_inbox_nameInbox criada pelo bridge.
statusactive / paused / error.
last_errorÚltima mensagem de erro reportada pelo bridge.

​
Próximos passos

Ativar integração

Provisione a integração com POST /api/chatwoot/set/:instance.

Erros do Chatwoot

Tabela de mapeamento dos status HTTP e mensagens vindas do bridge.