Skip to main content

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.

The integration with Chatwoot happens through the RyzeIntegrations microservice (bridge). RyzeAPI does not talk directly to Chatwoot, all communication goes through the bridge, which creates the inbox in Chatwoot and maintains a persistent WebSocket connection to RyzeAPI.
When the server has no BRIDGE_URL or BRIDGE_TOKEN configured, all module endpoints return 503 with the message integration gateway not configured (set BRIDGE_URL and BRIDGE_TOKEN). In addition, the internal route /ws/chatwoot/:instance is not registered (responds 404).

​
How it works

[ Client ] ──POST /api/chatwoot/set──► [ RyzeAPI ] ──POST /v1/integrations/activate──► [ RyzeIntegrations ]
                                                                                                  │
                                                                                                  ├─► creates inbox in Chatwoot
                                                                                                  └─► opens persistent WS
                                                                                                      at /ws/chatwoot/:instance
                                                                                                      (authenticated by BRIDGE_TOKEN)
The inbox created by the bridge starts receiving WhatsApp messages via RyzeAPI events. Messages sent by the Chatwoot agent flow back to RyzeAPI and are dispatched by whatsmeow.

​
Management endpoints

Activate

POST /api/chatwoot/set/:instance, provisions the integration (creates inbox + opens WS).

Status / Info

GET /api/chatwoot/list/:instance, local read enriched with live data from the bridge.

Deactivate

DELETE /api/chatwoot/delete/:instance, removes the integration and deletes the inbox in Chatwoot.

​
Inline activation when creating the instance

The integration can be activated together with instance creation, without a separate set call. Just include the chatwoot* block in the body of POST /api/instance/new: 
{
  "name": "suporte",
  "chatwootEnabled": true,
  "chatwootBaseUrl": "https://chatwoot.example.com",
  "chatwootAccountId": 5,
  "chatwootApiToken": "sk_live_abc123...",
  "chatwootInboxName": "WhatsApp - Orion"
}
If activation fails (wrong token, unreachable host, bridge offline), the instance is still created, the chatwoot object comes back with status: "error" and error: "<message>". You can then call POST /api/chatwoot/set/:instance to fix the credentials without recreating the instance.

​
Server environment variables

Whoever operates the platform needs to configure these variables to enable the module:
VariableDescription
BRIDGE_URLBase URL of RyzeIntegrations (e.g., https://bridge.example.com).
BRIDGE_TOKENService-to-service Bearer token.
BRIDGE_INTERNAL_RYZEAPI_URLURL the bridge uses to call RyzeAPI (useful in container-to-container deployments). Default: BASE_URL.

​
Detect whether the bridge is enabled

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

# 503 → bridge not configured on the server
# 404 → bridge active, but instance/integration does not exist
# 200 → bridge active and integration configured

​
Internal route /ws/chatwoot/:instance

This route is exclusive to the RyzeIntegrations bridge, it authenticates only via BRIDGE_TOKEN and does not accept TokenAccount or TokenInstance. It lives in a WebSocket hub separate from the public /ws/:instance; backpressure on one side does not affect the other. You should not consume this route directly.

​
Data model

The server persists each integration in the chatwoot_integrations table. The chatwootApiToken is encrypted at rest with AES-256-GCM and is never returned by the API.
FieldDescription
bridge_integration_idID returned by RyzeIntegrations.
chatwoot_base_urlURL of the Chatwoot installation.
chatwoot_account_idNumeric ID of the Chatwoot account.
chatwoot_inbox_id / chatwoot_inbox_nameInbox created by the bridge.
statusactive / paused / error.
last_errorLast error message reported by the bridge.

​
Next steps

Activate integration

Provision the integration with POST /api/chatwoot/set/:instance.

Chatwoot errors

Mapping table of HTTP status codes and messages from the bridge.