Saltar al contenido principal
POST
/
api
/
chatwoot
/
set
/
:instance
Activar integración
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
}
'

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.

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

​
Descripción

Activa la integración de Chatwoot para una instancia. El servidor envía la configuración al bridge RyzeIntegrations, que crea un inbox en Chatwoot y abre una conexión WebSocket persistente para recibir eventos de RyzeAPI. El chatwootApiToken se cifra en reposo con AES-256-GCM y nunca se devuelve por la API.
Esta operación tiene un timeout interno de 60 s, la primera activación implica crear el inbox y abrir el WebSocket, 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
  }'

​
Respuesta exitosa

201 Created
{
  "instance": "suporte",
  "status": "active",
  "bridge_integration_id": "int_xyz789abc",
  "message": "chatwoot integration activated"
}
CampoDescripción
instanceNombre de la instancia donde se activó la integración.
status"active" cuando la activación se completó en el bridge.
bridge_integration_idID devuelto por RyzeIntegrations, referencia para llamadas en vivo y DELETE.
messageMensaje fijo de confirmación.

​
Parámetros de ruta

​
instance
string
requerido
Nombre de la instancia (p. ej., suporte).

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.
​
Content-Type
string
requerido
application/json

​
Cuerpo de la solicitud

​
chatwootBaseUrl
string
requerido
URL de la instalación de Chatwoot (RFC 3986). La / final se elimina. Ejemplo: https://chatwoot.example.com.
​
chatwootAccountId
integer
requerido
ID numérico de la cuenta de Chatwoot. Debe ser mayor que 0.
​
chatwootApiToken
string
requerido
Token de API (access_token) del agente de Chatwoot. Cifrado en reposo con AES-256-GCM y nunca devuelto por la API.
​
inboxName
string
predeterminado:"RyzeAPI"
Nombre del inbox que se creará en Chatwoot.
​
signMessages
boolean
Cuando es true, antepone a los mensajes enviados por RyzeAPI la firma del agente de Chatwoot.
​
ignoreGroups
boolean
Cuando es true, los eventos de grupos no se enrutan a Chatwoot.
​
startAsPending
boolean
Cuando es true, las nuevas conversaciones inician como pending (en lugar de open).
​
reopenResolved
boolean
Cuando es true, los nuevos mensajes en conversaciones marcadas como resolved las reabren automáticamente.

​
Errores

La API intenta clasificar el fallo proveniente del bridge para devolver un estado HTTP útil + un mensaje accionable. El texto crudo del bridge (con la causa raíz de Chatwoot) se incluye después de Detail:.
HTTPerror.messageCausa
400Chatwoot account or endpoint not found — verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...ID de cuenta incorrecto, URL inválida o Chatwoot devolvió 404/422.
400Chatwoot rejected the request as invalid ... Detail: ...Error 422 de Chatwoot (validación de payload).
400invalid body: ...Cuerpo malformado o campos requeridos ausentes.
401Chatwoot rejected the API token — verify chatwootApiToken. Detail: ...Token de Chatwoot inválido (Chatwoot devolvió HTTP 401: Invalid Access Token).
403Chatwoot denied the request — verify the API token has admin scope on account <id>. Detail: ...El token no tiene permisos de administrador en la cuenta.
404instance not foundLa instancia no existe en RyzeAPI.
500chatwoot integration failed: persist integration: ...Fallo de persistencia 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, o Chatwoot devolvió 5xx.
503integration gateway not configured (set BRIDGE_URL and BRIDGE_TOKEN)Bridge no configurado 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"
  }
}

​
Siguiente

Ver estado / información

Consulta status y last_error enriquecidos con datos en vivo del bridge.

Desactivar integración

Elimina la integración local + bridge y borra el inbox en Chatwoot.