Activate integration

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

Three inbox modes, controlled by createInbox and inboxId:

Create automatically (default) — createInbox: true (or omitted) and no inboxId. RyzeAPI creates a new inbox in Chatwoot and points its webhook at itself.
Reuse an existing inbox — pass inboxId. RyzeAPI repoints that inbox’s API channel webhook to itself (PATCH /inboxes/:id with channel.webhook_url), preserving contacts, history, and agents. Ideal for migrating from another WhatsApp API without switching inboxes.
Webhook only (manual) — createInbox: false and no inboxId. RyzeAPI just activates the integration and returns webhook_url in the response; paste that URL into the Webhook URL field of your inbox’s API channel in Chatwoot. The inbox_id is learned from the first incoming event.

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

await fetch("https://ryzeapi.cloud/api/chatwoot/set/suporte", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    chatwootBaseUrl:   "https://chatwoot.example.com",
    chatwootAccountId: 5,
    chatwootApiToken:  "sk_live_abc123...",
    inboxName:         "WhatsApp - Orion",
    signMessages:      true,
    ignoreGroups:      false,
    startAsPending:    false,
    reopenResolved:    true
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/chatwoot/set/suporte",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "chatwootBaseUrl":   "https://chatwoot.example.com",
        "chatwootAccountId": 5,
        "chatwootApiToken":  "sk_live_abc123...",
        "inboxName":         "WhatsApp - Orion",
        "signMessages":      True,
        "ignoreGroups":      False,
        "startAsPending":    False,
        "reopenResolved":    True
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "chatwootBaseUrl":   "https://chatwoot.example.com",
        "chatwootAccountId": 5,
        "chatwootApiToken":  "sk_live_abc123...",
        "inboxName":         "WhatsApp - Orion",
        "signMessages":      true,
        "ignoreGroups":      false,
        "startAsPending":    false,
        "reopenResolved":    true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chatwoot/set/suporte", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Success response

201 Created

{
  "instance": "suporte",
  "status": "active",
  "bridge_integration_id": "int_xyz789abc",
  "webhook_url": "https://bridge.ryzeapi.cloud/v1/chatwoot/webhook/int_xyz789abc",
  "message": "chatwoot integration activated"
}

Field	Description
`instance`	Name of the instance where the integration was activated.
`status`	`"active"` when activation completed.
`bridge_integration_id`	Internal integration ID, used as a reference in the other operations.
`webhook_url`	URL Chatwoot should call (API channel webhook). In create/reuse modes RyzeAPI configures it in Chatwoot for you; in webhook-only mode, paste it manually.
`message`	Fixed confirmation message.

Path parameters

string

required

Instance name (e.g., suporte).

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json

Request body

string

required

URL of the Chatwoot installation (RFC 3986). The trailing / is removed. Example: https://chatwoot.example.com.

integer

required

Numeric ID of the Chatwoot account. Must be greater than 0.

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.

string

default:"RyzeAPI"

Name of the inbox to be created in Chatwoot (used only when a new inbox is created).

boolean

default:"true"

Controls automatic inbox creation. true (or absent) with no inboxId creates a new inbox. false with no inboxId enables webhook-only mode: no inbox is created and the response includes webhook_url for you to paste into Chatwoot.

integer

ID of an existing Chatwoot inbox to reuse. When set (must be > 0), RyzeAPI repoints that inbox’s webhook instead of creating a new one, and takes precedence over createInbox.

boolean

When true, prefixes messages sent by RyzeAPI with the Chatwoot agent’s signature.

boolean

When true, group events are not routed to Chatwoot.

boolean

When true, new conversations start as pending (instead of open).

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

HTTP	`error.message`	Cause
400	`Chatwoot account or endpoint not found - verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...`	Wrong account ID, invalid URL, or Chatwoot returned 404/422.
400	`Chatwoot rejected the request as invalid ... Detail: ...`	Chatwoot 422 error (payload validation).
400	`invalid body: ...`	Malformed body or missing required fields.
401	`Chatwoot rejected the API token - verify chatwootApiToken. Detail: ...`	Invalid Chatwoot token (Chatwoot returned `HTTP 401: Invalid Access Token`).
403	`Chatwoot denied the request - verify the API token has admin scope on account <id>. Detail: ...`	Token lacks admin scope on the account.
404	`instance not found`	Instance does not exist in RyzeAPI.
500	`chatwoot integration failed: persist integration: ...`	Local persistence failure (DB).
502	`Chatwoot 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.
503	`integration gateway not configured`	Chatwoot 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"
  }
}

View status / info

Check the status and last_error of the integration.

Deactivate integration

Remove the integration (the Chatwoot inbox is preserved).

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Activate integration

Description

Example

Success response

Path parameters

Headers

Request body

Errors

Error payload examples

Next

View status / info

Deactivate integration

​Description

​Example

​Success response

​Path parameters

​Headers

​Request body

​Errors

​Error payload examples

​Next

View status / info

Deactivate integration

Description

Example

Success response

Path parameters

Headers

Request body

Errors

Error payload examples

Next