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

​
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ó.
bridge_integration_idID interno de la integración, usado como referencia en las demás operaciones.
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. No es devuelto por este endpoint, pero se expone en plaintext en GET /api/chatwoot/list/:instance.
​
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 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:.
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 configuredMó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"
  }
}

​
Siguiente

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