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

# Activate integration

> Provision the Chatwoot integration: creates the inbox in Chatwoot and enables message routing

**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`](/en/api/chatwoot/info)).

<Warning>
  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.
</Warning>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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
    })
  });
  ```

  ```python Python theme={null}
  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
      }
  )
  ```

  ```go Go theme={null}
  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)
  }
  ```
</CodeGroup>

## Success response

```json 201 Created theme={null}
{
  "instance": "suporte",
  "status": "active",
  "bridge_integration_id": "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. |
| `message`               | Fixed confirmation message.                                           |

## Path parameters

<ParamField path="instance" type="string" required>
  Instance name (e.g., `suporte`).
</ParamField>

## Headers

<ParamField header="token" type="string" required>
  `TokenAccount` or `TokenInstance`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Request body

<ParamField body="chatwootBaseUrl" type="string" required>
  URL of the Chatwoot installation (RFC 3986). The trailing `/` is removed. Example: `https://chatwoot.example.com`.
</ParamField>

<ParamField body="chatwootAccountId" type="integer" required>
  Numeric ID of the Chatwoot account. Must be greater than `0`.
</ParamField>

<ParamField body="chatwootApiToken" type="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`](/en/api/chatwoot/info).
</ParamField>

<ParamField body="inboxName" type="string" default="RyzeAPI">
  Name of the inbox to be created in Chatwoot.
</ParamField>

<ParamField body="signMessages" type="boolean">
  When `true`, prefixes messages sent by RyzeAPI with the Chatwoot agent's signature.
</ParamField>

<ParamField body="ignoreGroups" type="boolean">
  When `true`, group events are not routed to Chatwoot.
</ParamField>

<ParamField body="startAsPending" type="boolean">
  When `true`, new conversations start as `pending` (instead of `open`).
</ParamField>

<ParamField body="reopenResolved" type="boolean">
  When `true`, new messages on conversations marked as `resolved` automatically reopen them.
</ParamField>

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

<Tip>
  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.
</Tip>

### Error payload examples

Invalid token:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="View status / info" icon="circle-info" href="/en/api/chatwoot/info">
    Check the `status` and `last_error` of the integration.
  </Card>

  <Card title="Deactivate integration" icon="power-off" href="/en/api/chatwoot/deactivate">
    Remove the integration (the Chatwoot inbox is preserved).
  </Card>
</CardGroup>