Retrieve a channel

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

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.

Authorization: Bearer rfl_live_...

Path parameters

string

required

Channel ID, as returned by List channels.

Response

Returns a Channel object with three extra fields:

integer | null

Conversation data on this channel is deleted after this many days. 0 or null keeps it indefinitely.

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

object

Configuration for the channel’s type.

Show email

string

The address customers write to.

string

Sender name on outgoing email.

string | null

Reply-To override, if set.

string | null

Internal description of the inbox.

string

forwarding, microsoft (Microsoft 365) or google (Google Workspace).

object | null

Mailbox connection for microsoft and google; null for forwarding or when nothing is connected.

Show properties

string

pending, connected, needs_reauth or disconnected.

string | null

ISO 8601 UTC timestamp of the last complete mailbox read. Microsoft 365 only.

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.

object

How the AI handles incoming email. { "mode": "off" }, { "mode": "approval" } (the AI drafts, a person sends) or { "mode": "autopilot", "replyDelayMinutes", "aiDisplayName" }.

object

human and ai signature text (or null), plus useForNewMessages and useForReplies booleans.

string | null

Automatic acknowledgement text, if set.

string | null

ISO 8601 UTC timestamp of when the inbox went live. null while it is observing.

Show chatbot

string

floating, panel, page or search.

object

default language code and the enabled language codes.

object

Who answers first and where conversations go next.

Show properties

string

ai (the AI answers first), live_chat_first (a person answers first) or disabled.

string

Only when entry is ai: how readily the AI hands over — lazy, neutral or eager.

object

primary and fallback hand-over targets: live_chat, email or null.

object

Whether the widget asks for name and phone, and whether it verifies email (verifyEmail).

string[]

Sites the widget may load on. Empty means any site.

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

boolean

true when the widget only chats with visitors identified via user identification.

string

explicit, implicit or none.

Show form

string

Form heading.

string | null

Text shown under the heading.

array

Each field’s label, type (text, email, textarea, select, checkbox, phone or number) and required.

object | null

The email inbox submissions land in (id, name), or null.

string[]

Sites the form may load on. Empty means any site.

string | null

Where the visitor goes after submitting, if set.

Examples

Fetch a channel

curl https://api.replyful.com/v1/channels/p8w4d1zt \
  -H "Authorization: Bearer rfl_live_..."

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

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

Response

{
  "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": "[email protected]",
    "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 for the full error envelope reference.

Documentation

Tickets

Channels

Conversations

Knowledge

Retrieve a channel

Authentication

Path parameters

Response

Examples

Fetch a channel

Error responses

​Authentication

​Path parameters

​Response

​Examples

​Fetch a channel

​Error responses

Authentication

Path parameters

Response

Examples

Fetch a channel

Error responses