Ativar integração

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

Três modos de caixa de entrada, definidos por createInbox e inboxId:

Criar automaticamente (padrão) — createInbox: true (ou omitido) e sem inboxId. A RyzeAPI cria uma inbox nova no Chatwoot e já aponta o webhook dela para si.
Reusar uma inbox existente — informe o inboxId. A RyzeAPI reaponta o webhook do canal API dessa inbox para si (PATCH /inboxes/:id com channel.webhook_url), preservando contatos, histórico e agentes. Ideal para migrar de outra API de WhatsApp sem trocar de caixa de entrada.
Somente webhook (manual) — createInbox: false e sem inboxId. A RyzeAPI apenas ativa a integração e devolve webhook_url na resposta; cole essa URL no campo Webhook URL do canal API da sua inbox no Chatwoot. O inbox_id é aprendido no primeiro evento recebido.

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
  }'

await fetch("https://ryzeapi.cloud/api/chatwoot/set/suporte", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    chatwootBaseUrl:   "https://chatwoot.example.com",
    chatwootAccountId: 5,
    chatwootApiToken:  "sk_live_abc123...",
    inboxName:         "WhatsApp - Orion",
    signMessages:      true,
    ignoreGroups:      false,
    startAsPending:    false,
    reopenResolved:    true
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/chatwoot/set/suporte",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "chatwootBaseUrl":   "https://chatwoot.example.com",
        "chatwootAccountId": 5,
        "chatwootApiToken":  "sk_live_abc123...",
        "inboxName":         "WhatsApp - Orion",
        "signMessages":      True,
        "ignoreGroups":      False,
        "startAsPending":    False,
        "reopenResolved":    True
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "chatwootBaseUrl":   "https://chatwoot.example.com",
        "chatwootAccountId": 5,
        "chatwootApiToken":  "sk_live_abc123...",
        "inboxName":         "WhatsApp - Orion",
        "signMessages":      true,
        "ignoreGroups":      false,
        "startAsPending":    false,
        "reopenResolved":    true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chatwoot/set/suporte", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Resposta de sucesso

201 Created

{
  "instance": "suporte",
  "status": "active",
  "bridge_integration_id": "int_xyz789abc",
  "webhook_url": "https://bridge.ryzeapi.cloud/v1/chatwoot/webhook/int_xyz789abc",
  "message": "chatwoot integration activated"
}

Campo	Descrição
`instance`	Nome da instância onde a integração foi ativada.
`status`	`"active"` quando a ativação foi concluída.
`bridge_integration_id`	ID interno da integração, usado como referência nas demais operações.
`webhook_url`	URL que o Chatwoot deve chamar (webhook do canal API). Nos modos de criação/reuso a RyzeAPI já a configura no Chatwoot; no modo somente webhook cole-a manualmente.
`message`	Mensagem fixa de confirmação.

Parâmetros de rota

string

obrigatório

Nome da instância (ex.: suporte).

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

string

obrigatório

URL da instalação Chatwoot (RFC 3986). O / final é removido. Ex.: https://chatwoot.example.com.

integer

obrigatório

ID numérico da conta Chatwoot. Precisa ser maior que 0.

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.

string

padrão:"RyzeAPI"

Nome do inbox a ser criado no Chatwoot (usado apenas quando uma inbox nova é criada).

boolean

padrão:"true"

Controla a criação automática da inbox. true (ou ausente) e sem inboxId cria uma inbox nova. false e sem inboxId ativa o modo somente webhook: nenhuma inbox é criada e a resposta traz webhook_url para você colar no Chatwoot.

integer

ID de uma inbox já existente no Chatwoot para reusar. Quando informado (precisa ser > 0), a RyzeAPI reaponta o webhook dessa inbox em vez de criar uma nova, e tem precedência sobre createInbox.

boolean

Se true, prefixa mensagens enviadas pela RyzeAPI com a assinatura do agente Chatwoot.

boolean

Se true, eventos de grupo não são roteados para o Chatwoot.

boolean

Se true, conversas novas começam como pending (em vez de open).

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

HTTP	`error.message`	Causa
400	`Chatwoot account or endpoint not found - verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...`	Account ID errado, URL inválida ou Chatwoot devolveu 404/422.
400	`Chatwoot rejected the request as invalid ... Detail: ...`	Erro 422 do Chatwoot (validação do payload).
400	`invalid body: ...`	Body malformado ou campos obrigatórios ausentes.
401	`Chatwoot rejected the API token - verify chatwootApiToken. Detail: ...`	Token Chatwoot inválido (Chatwoot devolveu `HTTP 401: Invalid Access Token`).
403	`Chatwoot denied the request - verify the API token has admin scope on account <id>. Detail: ...`	Token sem escopo de admin na conta.
404	`instance not found`	Instância não existe na RyzeAPI.
500	`chatwoot integration failed: persist integration: ...`	Falha de persistência local (DB).
502	`Chatwoot 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.
503	`integration gateway not configured`	Mó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"
  }
}

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

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Ativar integração

Descrição

Exemplo

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Erros

Exemplos de payload de erro

Próximo

Ver status / info

Desativar integração

​Descrição

​Exemplo

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Erros

​Exemplos de payload de erro

​Próximo

Ver status / info

Desativar integração

Descrição

Exemplo

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Erros

Exemplos de payload de erro

Próximo