> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chowder.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Channel

> Connect a channel to an instance by providing its configuration.

Connects a channel to the instance. What happens next depends on the channel's connection type:

* **Token-based channels** (like Discord or Telegram): provide the required credentials in `config` and the channel connects immediately.
* **Interactive channels** (like WhatsApp): the connection starts a pairing flow. You'll get back QR data to scan, and the status will be `"awaiting_scan"` until the user completes the process.

Behind the scenes, this writes the configuration to `openclaw.json` and restarts the gateway.

## Authentication

Requires an **org-level API key** or a **scoped token** with the `channels` permission.

## Path Parameters

<ParamField path="instance_id" type="string" required>
  The ID of the instance.
</ParamField>

<ParamField path="channel" type="string" required>
  The channel identifier (e.g. `discord`, `whatsapp`).
</ParamField>

## Body Parameters

<ParamField body="config" type="object" required>
  A key-value map of configuration fields for this channel. Use the [channel info endpoint](/api-reference/channels/info) to discover which fields are required. For interactive channels, you can optionally provide extra config.
</ParamField>

## Response

<ResponseField name="channel" type="string">
  The channel identifier.
</ResponseField>

<ResponseField name="status" type="string">
  Either `"connected"` (channel is live) or `"awaiting_scan"` (interactive channels waiting for user action).
</ResponseField>

<ResponseField name="qr_data" type="string">
  Raw QR code data for interactive channels. Only present when `status` is `"awaiting_scan"`.
</ResponseField>

<ResponseField name="qr_image_base64" type="string">
  Base64-encoded PNG image of the QR code. Only present when `status` is `"awaiting_scan"`.
</ResponseField>

<ResponseField name="message" type="string">
  An optional human-readable status message.
</ResponseField>

<RequestExample>
  ```bash cURL (token-based) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -X POST https://api.chowder.dev/v1/instances/ins_abc123/channels/discord/connect \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "config": {
        "token": "MTIz..."
      }
    }'
  ```

  ```bash cURL (interactive) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -X POST https://api.chowder.dev/v1/instances/ins_abc123/channels/whatsapp/connect \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "config": {}
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (token-based) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "channel": "discord",
    "status": "connected",
    "message": "Channel connected successfully."
  }
  ```

  ```json 200 (interactive) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "channel": "whatsapp",
    "status": "awaiting_scan",
    "qr_data": "2@ABC123...",
    "qr_image_base64": "iVBORw0KGgo..."
  }
  ```
</ResponseExample>