Skip to main content
POST
/
api
/
chatwoot
/
set
/
:instance
Activate integration
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 or TokenInstance • Rate limit: Global (100/min) • Idempotent: no

​
Description

Activates the Chatwoot integration for an instance. The server sends the configuration to the RyzeIntegrations bridge, which creates an inbox in Chatwoot and opens a persistent WebSocket connection to receive RyzeAPI events. The chatwootApiToken is encrypted at rest with AES-256-GCM and is never returned by the API.
This operation has an internal timeout of 60s, the first activation involves creating the inbox and opening the WebSocket, which can take time depending on latency to Chatwoot.

​
Example

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

​
Success response

201 Created
{
  "instance": "suporte",
  "status": "active",
  "bridge_integration_id": "int_xyz789abc",
  "message": "chatwoot integration activated"
}
FieldDescription
instanceName of the instance where the integration was activated.
status"active" when activation completed on the bridge.
bridge_integration_idID returned by RyzeIntegrations, reference for live calls and DELETE.
messageFixed confirmation message.

​
Path parameters

​
instance
string
required
Instance name (e.g., suporte).

​
Headers

​
token
string
required
TokenAccount or TokenInstance.
​
Content-Type
string
required
application/json

​
Request body

​
chatwootBaseUrl
string
required
URL of the Chatwoot installation (RFC 3986). The trailing / is removed. Example: https://chatwoot.example.com.
​
chatwootAccountId
integer
required
Numeric ID of the Chatwoot account. Must be greater than 0.
​
chatwootApiToken
string
required
API token (access_token) of the Chatwoot agent. Encrypted at rest with AES-256-GCM and never returned by the API.
​
inboxName
string
default:"RyzeAPI"
Name of the inbox to be created in Chatwoot.
​
signMessages
boolean
When true, prefixes messages sent by RyzeAPI with the Chatwoot agent’s signature.
​
ignoreGroups
boolean
When true, group events are not routed to Chatwoot.
​
startAsPending
boolean
When true, new conversations start as pending (instead of open).
​
reopenResolved
boolean
When true, new messages on conversations marked as resolved automatically reopen them.

​
Errors

The API tries to classify the failure coming from the bridge to return a useful HTTP status + an actionable message. The raw bridge text (with the root cause from Chatwoot) is included after Detail:.
HTTPerror.messageCause
400Chatwoot account or endpoint not found — verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...Wrong account ID, invalid URL, or Chatwoot returned 404/422.
400Chatwoot rejected the request as invalid ... Detail: ...Chatwoot 422 error (payload validation).
400invalid body: ...Malformed body or missing required fields.
401Chatwoot rejected the API token — verify chatwootApiToken. Detail: ...Invalid Chatwoot token (Chatwoot returned HTTP 401: Invalid Access Token).
403Chatwoot denied the request — verify the API token has admin scope on account <id>. Detail: ...Token lacks admin scope on the account.
404instance not foundInstance does not exist in RyzeAPI.
500chatwoot integration failed: persist integration: ...Local persistence failure (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, or Chatwoot returned 5xx.
503integration gateway not configured (set BRIDGE_URL and BRIDGE_TOKEN)Bridge not configured on the server.
Use the HTTP status to react programmatically (401 → fix token, 502 → re-check URL/connectivity) and show error.message to the end user, it already includes the suggested next action.

​
Error payload examples

Invalid token: 
{
  "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\"}"
  }
}
Unreachable host: 
{
  "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"
  }
}

​
Next

View status / info

Check the status and last_error enriched with live data from the bridge.

Deactivate integration

Remove the local + bridge integration and delete the inbox in Chatwoot.