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

# List channels

> GET /v1/channels — list chat widgets, email inboxes and forms with their live status and any issues that need attention

Returns a paginated list of your organization's active channels: chat widgets (`chatbot`), email inboxes (`email`) and forms (`form`). Archived channels are left out. Each channel carries the same status the Replyful dashboard shows, so you can check channel health from a script or monitoring job. For a channel's configuration, use [Retrieve a channel](/api-reference/channels/retrieve).

```http theme={null}
GET /v1/channels
```

## Authentication

Bearer token in the `Authorization` header. Read-only keys work. See [Authentication](/api-reference/authentication).

```http theme={null}
Authorization: Bearer rfl_live_...
```

## Query parameters

<ParamField query="limit" type="integer" default="20">
  Number of channels per page. Range `1`–`100`.
</ParamField>

<ParamField query="startingAfter" type="string">
  Opaque cursor from the previous response's `nextCursor`. See [Pagination](/api-reference/pagination).
</ParamField>

<ParamField query="type" type="string">
  Only return channels of this type. One of `chatbot`, `email`, `form`.
</ParamField>

Channels are ordered by `createdAt` ascending (oldest first).

## Response

Returns a [list envelope](/api-reference/pagination#response-shape) containing `Channel` objects.

### The Channel object

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

<ResponseField name="object" type="string">
  Always `"channel"`.
</ResponseField>

<ResponseField name="type" type="string">
  `chatbot` (chat widget), `email` (email inbox) or `form`.
</ResponseField>

<ResponseField name="name" type="string">
  The channel's name in the dashboard.
</ResponseField>

<ResponseField name="status" type="object">
  The channel's current state, derived the same way the dashboard does it.

  <Expandable title="properties">
    <ResponseField name="state" type="string">
      One of:

      * `live` — the channel is running.
      * `observing` — an email inbox that isn't live yet: Replyful mirrors the mailbox into tickets, but nothing is sent from Replyful and the AI doesn't run.
      * `paused` — the channel was paused in the dashboard.
      * `needs_attention` — something blocks the channel; see `issues`.
      * `archived` — the channel was archived. Only returned by [Retrieve a channel](/api-reference/channels/retrieve).
    </ResponseField>

    <ResponseField name="since" type="string | null">
      ISO 8601 UTC timestamp of when the channel entered `state`, or `null` when that moment isn't recorded (always `null` for `needs_attention`).
    </ResponseField>

    <ResponseField name="issues" type="array">
      What needs fixing, in plain language. Empty unless something is wrong. A paused channel can still list issues.

      <Expandable title="properties">
        <ResponseField name="code" type="string">Stable machine-readable code. See [Issue codes](#issue-codes).</ResponseField>
        <ResponseField name="message" type="string">Human-readable explanation with the fix. May change between releases — branch on `code`.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="agent" type="object | null">
  The AI agent assigned to the channel, or `null` if none.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Agent ID.</ResponseField>
    <ResponseField name="name" type="string">Agent name.</ResponseField>
    <ResponseField name="disabled" type="boolean">`true` when the agent has been disabled.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 UTC timestamp of channel creation.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 UTC timestamp of the most recent update.
</ResponseField>

### Issue codes

Issues only apply to email inboxes today.

| Code | When |
| - | - |
| `mailbox_not_connected` | A Microsoft 365 or Google Workspace inbox has no connected mailbox. |
| `reconnect_needed` | The mailbox connection expired and must be reconnected. |
| `mailbox_disconnected` | The mailbox was disconnected. |
| `sync_stalled` | Replyful hasn't been able to read a Microsoft 365 mailbox for over 6 hours. |
| `missing_domain` | A forwarding inbox has no sending domain. |
| `domain_not_verified` | The custom sending domain's DNS setup isn't verified yet. |

## Examples

### Find channels that need attention

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.replyful.com/v1/channels?limit=100" \
    -H "Authorization: Bearer rfl_live_..."
  ```

  ```ts Node.js theme={null}
  const res = await fetch("https://api.replyful.com/v1/channels?limit=100", {
    headers: { Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}` },
  });
  const { data } = await res.json();
  const broken = data.filter((c) => c.status.state === "needs_attention");
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.get(
      "https://api.replyful.com/v1/channels",
      headers={"Authorization": f"Bearer {os.environ['REPLYFUL_API_KEY']}"},
      params={"limit": 100},
  )
  res.raise_for_status()
  broken = [c for c in res.json()["data"] if c["status"]["state"] == "needs_attention"]
  ```
</CodeGroup>

```json Response theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "k3v9x2qa",
      "object": "channel",
      "type": "chatbot",
      "name": "Website chat",
      "status": { "state": "live", "since": "2026-03-02T09:00:00.000Z", "issues": [] },
      "agent": { "id": "ag7hq2mx", "name": "Ava", "disabled": false },
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-04-18T12:40:00.000Z"
    },
    {
      "id": "p8w4d1zt",
      "object": "channel",
      "type": "email",
      "name": "Support",
      "status": {
        "state": "needs_attention",
        "since": null,
        "issues": [
          {
            "code": "reconnect_needed",
            "message": "The Microsoft 365 mailbox needs to be reconnected. Use Reconnect in the channel's email settings."
          }
        ]
      },
      "agent": { "id": "ag7hq2mx", "name": "Ava", "disabled": false },
      "createdAt": "2026-03-05T14:12:00.000Z",
      "updatedAt": "2026-05-01T08:03:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "url": "/v1/channels"
}
```

## Error responses

| Status | `error.code` | When |
| - | - | - |
| `401` | `missing_api_key` | The `Authorization` header is absent. |
| `401` | `invalid_api_key` | The token is malformed, unknown, or archived. |
| `422` | `invalid_query_parameter` | `limit` or `type` is out of range. The `param` field names the offender. |
| `422` | `invalid_cursor` | The `startingAfter` cursor could not be decoded. |
| `429` | `too_many_requests` | Rate limit exceeded. Honor `Retry-After`. |

See [Errors](/api-reference/errors) for the full error envelope reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.