List channels

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.

GET /v1/channels

Authentication

Bearer token in the Authorization header. Read-only keys work. See Authentication.

Authorization: Bearer rfl_live_...

Query parameters

integer

default:"20"

Number of channels per page. Range 1–100.

string

Opaque cursor from the previous response’s nextCursor. See Pagination.

string

Only return channels of this type. One of chatbot, email, form.

Channels are ordered by createdAt ascending (oldest first).

Response

Returns a list envelope containing Channel objects.

The Channel object

string

Unique channel identifier.

string

Always "channel".

string

chatbot (chat widget), email (email inbox) or form.

string

The channel’s name in the dashboard.

object

The channel’s current state, derived the same way the dashboard does it.

Show properties

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.

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

array

What needs fixing, in plain language. Empty unless something is wrong. A paused channel can still list issues.

Show properties

string

Stable machine-readable code. See Issue codes.

string

Human-readable explanation with the fix. May change between releases — branch on code.

object | null

The AI agent assigned to the channel, or null if none.

Show properties

string

Agent ID.

string

Agent name.

boolean

true when the agent has been disabled.

string

ISO 8601 UTC timestamp of channel creation.

string

ISO 8601 UTC timestamp of the most recent update.

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

curl "https://api.replyful.com/v1/channels?limit=100" \
  -H "Authorization: Bearer rfl_live_..."

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");

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"]

Response

{
  "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 for the full error envelope reference.

Documentation

Tickets

Channels

Conversations

Knowledge

Authentication

Query parameters

Response

The Channel object

Issue codes

Examples

Find channels that need attention

Error responses

​Authentication

​Query parameters

​Response

​The Channel object

​Issue codes

​Examples

​Find channels that need attention

​Error responses

Authentication

Query parameters

Response

The Channel object

Issue codes

Examples

Find channels that need attention

Error responses