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

# Retrieve a channel

> GET /v1/channels/{id} — fetch one chat widget, email inbox or form with its status, AI agent, settings and per-type configuration

Returns a single channel with its status and configuration: AI mode and mailbox for an email inbox, routing and allowed domains for a chat widget, fields and routing for a form. Archived channels can still be retrieved and report `status.state: "archived"`.

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

Secrets, mailbox credentials and sync internals are never returned.

## Authentication

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

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

## Path parameters

<ParamField path="id" type="string" required>
  Channel ID, as returned by [List channels](/api-reference/channels/list).
</ParamField>

## Response

Returns a [`Channel` object](/api-reference/channels/list#the-channel-object) with three extra fields:

<ResponseField name="dataRetentionDays" type="integer | null">
  Conversation data on this channel is deleted after this many days. `0` or `null` keeps it indefinitely.
</ResponseField>

<ResponseField name="settings" type="object">
  Processing settings shared by every channel type. Each is an object with at least `enabled`:
  `aiSummary`, `urgency`, `insights`, `topics`, `aiDisclosure`, `utmTagging` (plus `source`, `medium`, `campaign`) and `autoResolve` (`enabled` and `afterHours` are omitted when the channel type's default applies).
</ResponseField>

<ResponseField name="config" type="object">
  Configuration for the channel's `type`.

  <Expandable title="email">
    <ResponseField name="inbox" type="string">The address customers write to.</ResponseField>
    <ResponseField name="displayName" type="string">Sender name on outgoing email.</ResponseField>
    <ResponseField name="replyTo" type="string | null">Reply-To override, if set.</ResponseField>
    <ResponseField name="description" type="string | null">Internal description of the inbox.</ResponseField>
    <ResponseField name="provider" type="string">`forwarding`, `microsoft` (Microsoft 365) or `google` (Google Workspace).</ResponseField>

    <ResponseField name="connection" type="object | null">
      Mailbox connection for `microsoft` and `google`; `null` for `forwarding` or when nothing is connected.

      <Expandable title="properties">
        <ResponseField name="status" type="string">`pending`, `connected`, `needs_reauth` or `disconnected`.</ResponseField>
        <ResponseField name="lastSyncedAt" type="string | null">ISO 8601 UTC timestamp of the last complete mailbox read. Microsoft 365 only.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="sendingDomain" type="string | object | null">
      Forwarding inboxes only. `"replyful"` when sending from the Replyful domain, `{ "domain", "verificationStatus" }` for a custom domain (`pending`, `verifying`, `verified` or `failed`), `null` when none is set or for other providers.
    </ResponseField>

    <ResponseField name="aiMode" type="object">
      How the AI handles incoming email. `{ "mode": "off" }`, `{ "mode": "approval" }` (the AI drafts, a person sends) or `{ "mode": "autopilot", "replyDelayMinutes", "aiDisplayName" }`.
    </ResponseField>

    <ResponseField name="signatures" type="object">`human` and `ai` signature text (or `null`), plus `useForNewMessages` and `useForReplies` booleans.</ResponseField>
    <ResponseField name="autoReply" type="string | null">Automatic acknowledgement text, if set.</ResponseField>
    <ResponseField name="liveAt" type="string | null">ISO 8601 UTC timestamp of when the inbox went live. `null` while it is `observing`.</ResponseField>
  </Expandable>

  <Expandable title="chatbot">
    <ResponseField name="layout" type="string">`floating`, `panel`, `page` or `search`.</ResponseField>
    <ResponseField name="languages" type="object">`default` language code and the `enabled` language codes.</ResponseField>

    <ResponseField name="routing" type="object">
      Who answers first and where conversations go next.

      <Expandable title="properties">
        <ResponseField name="entry" type="string">`ai` (the AI answers first), `live_chat_first` (a person answers first) or `disabled`.</ResponseField>
        <ResponseField name="eagerness" type="string">Only when `entry` is `ai`: how readily the AI hands over — `lazy`, `neutral` or `eager`.</ResponseField>
        <ResponseField name="escalation" type="object">`primary` and `fallback` hand-over targets: `live_chat`, `email` or `null`.</ResponseField>
        <ResponseField name="contactCapture" type="object">Whether the widget asks for `name` and `phone`, and whether it verifies email (`verifyEmail`).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="allowedDomains" type="string[]">Sites the widget may load on. Empty means any site.</ResponseField>
    <ResponseField name="audience" type="object">`ruleCount` (number of audience rules) and `fallback` — what a visitor who matches no rule can search: `open` (all knowledge) or `strict` (only knowledge not tied to an audience).</ResponseField>
    <ResponseField name="identityRequired" type="boolean">`true` when the widget only chats with visitors identified via [user identification](/user-identification).</ResponseField>
    <ResponseField name="privacyOptIn" type="string">`explicit`, `implicit` or `none`.</ResponseField>
  </Expandable>

  <Expandable title="form">
    <ResponseField name="title" type="string">Form heading.</ResponseField>
    <ResponseField name="description" type="string | null">Text shown under the heading.</ResponseField>
    <ResponseField name="fields" type="array">Each field's `label`, `type` (`text`, `email`, `textarea`, `select`, `checkbox`, `phone` or `number`) and `required`.</ResponseField>
    <ResponseField name="routesTo" type="object | null">The email inbox submissions land in (`id`, `name`), or `null`.</ResponseField>
    <ResponseField name="allowedDomains" type="string[]">Sites the form may load on. Empty means any site.</ResponseField>
    <ResponseField name="redirectUrl" type="string | null">Where the visitor goes after submitting, if set.</ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Fetch a channel

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

  ```ts Node.js theme={null}
  const res = await fetch("https://api.replyful.com/v1/channels/p8w4d1zt", {
    headers: { Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}` },
  });
  const channel = await res.json();
  ```

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

  res = requests.get(
      "https://api.replyful.com/v1/channels/p8w4d1zt",
      headers={"Authorization": f"Bearer {os.environ['REPLYFUL_API_KEY']}"},
  )
  res.raise_for_status()
  channel = res.json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "p8w4d1zt",
  "object": "channel",
  "type": "email",
  "name": "Support",
  "status": { "state": "live", "since": "2026-03-12T10:00:00.000Z", "issues": [] },
  "agent": { "id": "ag7hq2mx", "name": "Ava", "disabled": false },
  "createdAt": "2026-03-05T14:12:00.000Z",
  "updatedAt": "2026-05-01T08:03:00.000Z",
  "config": {
    "inbox": "support@acme.com",
    "displayName": "Acme Support",
    "replyTo": null,
    "description": null,
    "provider": "microsoft",
    "connection": {
      "status": "connected",
      "lastSyncedAt": "2026-05-01T08:00:00.000Z"
    },
    "sendingDomain": null,
    "aiMode": { "mode": "autopilot", "replyDelayMinutes": 5, "aiDisplayName": "Ava" },
    "signatures": {
      "human": "Best,\nThe Acme team",
      "ai": null,
      "useForNewMessages": true,
      "useForReplies": true
    },
    "autoReply": null,
    "liveAt": "2026-03-12T10:00:00.000Z"
  },
  "settings": {
    "aiSummary": { "enabled": true },
    "urgency": { "enabled": true },
    "insights": { "enabled": true },
    "topics": { "enabled": true },
    "utmTagging": { "enabled": false, "source": "replyful", "medium": "chatbot", "campaign": "" },
    "aiDisclosure": { "enabled": false },
    "autoResolve": {}
  },
  "dataRetentionDays": null
}
```

## 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. |
| `404` | `channel_not_found` | The channel does not exist or belongs to another organization. |
| `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.