Activar integración

Auth: TokenAccount o TokenInstance • Rate limit: Global (100/min) • Idempotente: no

Descripción

Activa la integración de Chatwoot para una instancia. RyzeAPI crea una inbox en Chatwoot y mantiene la conexión en tiempo real. El chatwootApiToken se cifra en reposo con AES-256-GCM y no es devuelto por este endpoint (solo se expone en plaintext en GET /api/chatwoot/list/:instance).

Tres modos de inbox, definidos por createInbox e inboxId:

Crear automáticamente (por defecto) — createInbox: true (u omitido) y sin inboxId. RyzeAPI crea una inbox nueva en Chatwoot y apunta su webhook hacia sí misma.
Reutilizar una inbox existente — indica el inboxId. RyzeAPI reapunta el webhook del canal API de esa inbox hacia sí misma (PATCH /inboxes/:id con channel.webhook_url), preservando contactos, historial y agentes. Ideal para migrar desde otra API de WhatsApp sin cambiar de inbox.
Solo webhook (manual) — createInbox: false y sin inboxId. RyzeAPI solo activa la integración y devuelve webhook_url en la respuesta; pega esa URL en el campo Webhook URL del canal API de tu inbox en Chatwoot. El inbox_id se aprende con el primer evento recibido.

Esta operación tiene un timeout interno de 60 s, la primera activación implica crear la inbox y abrir la conexión, lo que puede tardar dependiendo de la latencia hacia Chatwoot.

Ejemplo

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

Respuesta exitosa

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	Descripción
`instance`	Nombre de la instancia donde se activó la integración.
`status`	`"active"` cuando la activación se completó.
`bridge_integration_id`	ID interno de la integración, usado como referencia en las demás operaciones.
`webhook_url`	URL que Chatwoot debe llamar (webhook del canal API). En los modos de creación/reutilización RyzeAPI ya la configura en Chatwoot; en el modo solo webhook pégala manualmente.
`message`	Mensaje fijo de confirmación.

Parámetros de ruta

string

requerido

Nombre de la instancia (p. ej., suporte).

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

string

requerido

URL de la instalación de Chatwoot (RFC 3986). La / final se elimina. Ejemplo: https://chatwoot.example.com.

integer

requerido

ID numérico de la cuenta de Chatwoot. Debe ser mayor que 0.

string

requerido

Token de API (access_token) del agente de Chatwoot. Cifrado en reposo con AES-256-GCM. No es devuelto por este endpoint, pero se expone en plaintext en GET /api/chatwoot/list/:instance.

string

predeterminado:"RyzeAPI"

Nombre del inbox que se creará en Chatwoot (solo se usa cuando se crea una inbox nueva).

boolean

predeterminado:"true"

Controla la creación automática de la inbox. true (o ausente) y sin inboxId crea una inbox nueva. false y sin inboxId activa el modo solo webhook: no se crea ninguna inbox y la respuesta incluye webhook_url para que la pegues en Chatwoot.

integer

ID de una inbox ya existente en Chatwoot para reutilizar. Cuando se indica (debe ser > 0), RyzeAPI reapunta el webhook de esa inbox en lugar de crear una nueva, y tiene precedencia sobre createInbox.

boolean

Cuando es true, antepone a los mensajes enviados por RyzeAPI la firma del agente de Chatwoot.

boolean

Cuando es true, los eventos de grupos no se enrutan a Chatwoot.

boolean

Cuando es true, las nuevas conversaciones inician como pending (en lugar de open).

boolean

Cuando es true, los nuevos mensajes en conversaciones marcadas como resolved las reabren automáticamente.

Errores

La API clasifica el fallo y devuelve un estado HTTP útil con un mensaje accionable. El texto crudo de la causa raíz (proveniente de Chatwoot) se incluye después de Detail:.

HTTP	`error.message`	Causa
400	`Chatwoot account or endpoint not found - verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...`	ID de cuenta incorrecto, URL inválida o Chatwoot devolvió 404/422.
400	`Chatwoot rejected the request as invalid ... Detail: ...`	Error 422 de Chatwoot (validación de payload).
400	`invalid body: ...`	Cuerpo malformado o campos requeridos ausentes.
401	`Chatwoot rejected the API token - verify chatwootApiToken. Detail: ...`	Token de Chatwoot inválido (Chatwoot devolvió `HTTP 401: Invalid Access Token`).
403	`Chatwoot denied the request - verify the API token has admin scope on account <id>. Detail: ...`	El token no tiene permisos de administrador en la cuenta.
404	`instance not found`	La instancia no existe en RyzeAPI.
500	`chatwoot integration failed: persist integration: ...`	Fallo de persistencia 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`, o Chatwoot devolvió 5xx.
503	`integration gateway not configured`	Módulo Chatwoot no habilitado en el servidor.

Usa el estado HTTP para reaccionar de forma programática (401 → corregir token, 502 → revisar URL/conectividad) y muestra error.message al usuario final, ya incluye la siguiente acción sugerida.

Ejemplos de payload de error

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

{
  "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 estado / información

Consulta el status y el last_error de la integración.

Desactivar integración

Elimina la integración (la inbox en Chatwoot se conserva).

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Activar integración

Descripción

Ejemplo

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Errores

Ejemplos de payload de error

Siguiente

Ver estado / información

Desactivar integración

​Descripción

​Ejemplo

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Errores

​Ejemplos de payload de error

​Siguiente

Ver estado / información

Desactivar integración

Descripción

Ejemplo

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Errores

Ejemplos de payload de error

Siguiente