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
}
'
Auth: TokenAccount or TokenInstance • Rate limit: Global (100/min) • Idempotent: no

​
Description

Activates the Chatwoot integration for an instance. RyzeAPI creates an inbox in Chatwoot and keeps the realtime connection. The chatwootApiToken is encrypted at rest with AES-256-GCM and is not returned by this endpoint (it is exposed in plaintext only by GET /api/chatwoot/list/:instance).
This operation has an internal timeout of 60s, the first activation involves creating the inbox and opening the realtime connection, 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.
bridge_integration_idInternal integration ID, used as a reference in the other operations.
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. Not returned by this endpoint, but exposed in plaintext by GET /api/chatwoot/list/:instance.
​
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 classifies the failure and returns a useful HTTP status with an actionable message. The raw root-cause text (coming 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 configuredChatwoot module not enabled 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 of the integration.

Deactivate integration

Remove the integration (the Chatwoot inbox is preserved).