Pular para o conteúdo principal
POST
/
api
/
chatwoot
/
set
/
:instance
Ativar integração
curl --request POST \
  --url https://api.example.com/api/chatwoot/set/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "chatwootBaseUrl": "<string>",
  "chatwootAccountId": 123,
  "chatwootApiToken": "<string>",
  "inboxName": "<string>",
  "signMessages": true,
  "ignoreGroups": true,
  "startAsPending": true,
  "reopenResolved": true
}
'
Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

​
Descrição

Ativa a integração Chatwoot para uma instância. A RyzeAPI cria uma inbox no Chatwoot e mantém a conexão em tempo real. O chatwootApiToken é encriptado at-rest com AES-256-GCM e não é retornado por este endpoint (é exposto em plaintext apenas em GET /api/chatwoot/list/:instance).
Esta operação tem timeout interno de 60s, a primeira ativação envolve criação de inbox e abertura de WebSocket, o que pode demorar dependendo da latência até o Chatwoot.

​
Exemplo

curl -X POST "https://ryzeapi.cloud/api/chatwoot/set/suporte" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "chatwootBaseUrl":   "https://chatwoot.example.com",
    "chatwootAccountId": 5,
    "chatwootApiToken":  "sk_live_abc123...",
    "inboxName":         "WhatsApp - Orion",
    "signMessages":      true,
    "ignoreGroups":      false,
    "startAsPending":    false,
    "reopenResolved":    true
  }'

​
Resposta de sucesso

201 Created
{
  "instance": "suporte",
  "status": "active",
  "bridge_integration_id": "int_xyz789abc",
  "message": "chatwoot integration activated"
}
CampoDescrição
instanceNome da instância onde a integração foi ativada.
status"active" quando a ativação foi concluída.
bridge_integration_idID interno da integração, usado como referência nas demais operações.
messageMensagem fixa de confirmação.

​
Parâmetros de rota

​
instance
string
obrigatório
Nome da instância (ex.: suporte).

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance.
​
Content-Type
string
obrigatório
application/json

​
Request body

​
chatwootBaseUrl
string
obrigatório
URL da instalação Chatwoot (RFC 3986). O / final é removido. Ex.: https://chatwoot.example.com.
​
chatwootAccountId
integer
obrigatório
ID numérico da conta Chatwoot. Precisa ser maior que 0.
​
chatwootApiToken
string
obrigatório
API token (access_token) do agente Chatwoot. Encriptado at-rest com AES-256-GCM. Não é retornado por este endpoint, mas é exposto em plaintext em GET /api/chatwoot/list/:instance.
​
inboxName
string
padrão:"RyzeAPI"
Nome do inbox a ser criado no Chatwoot.
​
signMessages
boolean
Se true, prefixa mensagens enviadas pela RyzeAPI com a assinatura do agente Chatwoot.
​
ignoreGroups
boolean
Se true, eventos de grupo não são roteados para o Chatwoot.
​
startAsPending
boolean
Se true, conversas novas começam como pending (em vez de open).
​
reopenResolved
boolean
Se true, mensagens novas em conversas marcadas como resolved reabrem-nas automaticamente.

​
Erros

A API classifica a falha e devolve um status HTTP útil com uma mensagem acionável. O texto bruto da causa raiz (vinda do Chatwoot) é incluído após Detail:.
HTTPerror.messageCausa
400Chatwoot account or endpoint not found - verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...Account ID errado, URL inválida ou Chatwoot devolveu 404/422.
400Chatwoot rejected the request as invalid ... Detail: ...Erro 422 do Chatwoot (validação do payload).
400invalid body: ...Body malformado ou campos obrigatórios ausentes.
401Chatwoot rejected the API token - verify chatwootApiToken. Detail: ...Token Chatwoot inválido (Chatwoot devolveu HTTP 401: Invalid Access Token).
403Chatwoot denied the request - verify the API token has admin scope on account <id>. Detail: ...Token sem escopo de admin na conta.
404instance not foundInstância não existe na RyzeAPI.
500chatwoot integration failed: persist integration: ...Falha de persistência local (DB).
502Chatwoot is unreachable at <url> - verify chatwootBaseUrl and that the host is reachable from the server. Detail: ...DNS, connection refused, i/o timeout, dial tcp ou Chatwoot retornou 5xx.
503integration gateway not configuredMódulo Chatwoot não habilitado no servidor.
Use o status HTTP para reagir programaticamente (401 → corrigir token, 502 → reverificar URL/conectividade) e exiba error.message ao usuário final, ela já vem com a próxima ação sugerida.

​
Exemplos de payload de erro

Token inválido: 
{
  "success": false,
  "error": {
    "message": "Chatwoot rejected the API token - verify chatwootApiToken. Detail: https://chatwoot.example.com/api/v1/accounts/5/inboxes HTTP 401: {\"error\":\"Invalid Access Token\"}"
  }
}
Host inacessível: 
{
  "success": false,
  "error": {
    "message": "Chatwoot is unreachable at https://chatwoot.example.com - verify chatwootBaseUrl and that the host is reachable from the server. Detail: Post \"https://chatwoot.example.com/api/v1/accounts/5/inboxes\": dial tcp [::1]:443: connect: connection refused"
  }
}

​
Próximo

Ver status / info

Confira o status e o last_error da integração.

Desativar integração

Remova a integração (a inbox no Chatwoot é preservada).