Saltar al contenido principal

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.

La integración con Chatwoot se realiza a través del microservicio RyzeIntegrations (bridge). RyzeAPI no se comunica directamente con Chatwoot, toda la comunicación pasa por el bridge, que crea el inbox en Chatwoot y mantiene una conexión WebSocket persistente con RyzeAPI.
Cuando el servidor no tiene BRIDGE_URL o BRIDGE_TOKEN configurados, todos los endpoints del módulo devuelven 503 con el mensaje integration gateway not configured (set BRIDGE_URL and BRIDGE_TOKEN). Además, la ruta interna /ws/chatwoot/:instance no se registra (responde 404).

​
Cómo funciona

[ Cliente ] ──POST /api/chatwoot/set──► [ RyzeAPI ] ──POST /v1/integrations/activate──► [ RyzeIntegrations ]
                                                                                                  │
                                                                                                  ├─► crea inbox en Chatwoot
                                                                                                  └─► abre WS persistente
                                                                                                      en /ws/chatwoot/:instance
                                                                                                      (autenticado por BRIDGE_TOKEN)
El inbox creado por el bridge comienza a recibir mensajes de WhatsApp mediante eventos de RyzeAPI. Los mensajes enviados por el agente de Chatwoot regresan a RyzeAPI y son despachados por whatsmeow.

​
Endpoints de gestión

Activar

POST /api/chatwoot/set/:instance, provisiona la integración (crea el inbox + abre el WS).

Estado / Información

GET /api/chatwoot/list/:instance, lectura local enriquecida con datos en vivo del bridge.

Desactivar

DELETE /api/chatwoot/delete/:instance, elimina la integración y borra el inbox en Chatwoot.

​
Activación inline al crear la instancia

La integración puede activarse junto con la creación de la instancia, sin una llamada set separada. Solo incluye el bloque chatwoot* en el cuerpo de POST /api/instance/new: 
{
  "name": "suporte",
  "chatwootEnabled": true,
  "chatwootBaseUrl": "https://chatwoot.example.com",
  "chatwootAccountId": 5,
  "chatwootApiToken": "sk_live_abc123...",
  "chatwootInboxName": "WhatsApp - Orion"
}
Si la activación falla (token incorrecto, host inalcanzable, bridge offline), la instancia se crea de todos modos, el objeto chatwoot regresa con status: "error" y error: "<mensaje>". Luego puedes llamar a POST /api/chatwoot/set/:instance para corregir las credenciales sin recrear la instancia.

​
Variables de entorno del servidor

Quien opera la plataforma debe configurar estas variables para habilitar el módulo:
VariableDescripción
BRIDGE_URLURL base de RyzeIntegrations (p. ej., https://bridge.example.com).
BRIDGE_TOKENToken Bearer de servicio a servicio.
BRIDGE_INTERNAL_RYZEAPI_URLURL que el bridge utiliza para llamar a RyzeAPI (útil en despliegues contenedor a contenedor). Predeterminado: BASE_URL.

​
Detectar si el bridge está habilitado

curl -s -o /dev/null -w "%{http_code}\n" \
  "https://ryzeapi.cloud/api/chatwoot/list/qualquer-coisa" \
  -H "token: $Token_Account"

# 503 → bridge no configurado en el servidor
# 404 → bridge activo, pero la instancia/integración no existe
# 200 → bridge activo e integración configurada

​
Ruta interna /ws/chatwoot/:instance

Esta ruta es exclusiva del bridge RyzeIntegrations, se autentica únicamente mediante BRIDGE_TOKEN y no acepta TokenAccount ni TokenInstance. Vive en un hub de WebSocket separado del /ws/:instance público; la contrapresión en un lado no afecta al otro. No deberías consumir esta ruta directamente.

​
Modelo de datos

El servidor persiste cada integración en la tabla chatwoot_integrations. El chatwootApiToken se cifra en reposo con AES-256-GCM y nunca se devuelve por la API.
CampoDescripción
bridge_integration_idID devuelto por RyzeIntegrations.
chatwoot_base_urlURL de la instalación de Chatwoot.
chatwoot_account_idID numérico de la cuenta de Chatwoot.
chatwoot_inbox_id / chatwoot_inbox_nameInbox creado por el bridge.
statusactive / paused / error.
last_errorÚltimo mensaje de error reportado por el bridge.

​
Próximos pasos

Activar integración

Provisiona la integración con POST /api/chatwoot/set/:instance.

Errores de Chatwoot

Tabla de mapeo de códigos de estado HTTP y mensajes del bridge.