Skip to main content

​
Concept

A Channel is the connection between a Timely.ai agent and a messaging platform where your customers are. Each channel represents an active account or number: a WhatsApp Business number, an Instagram Business profile, a Telegram bot, or a chat widget embedded in your website. The agent associated with the channel receives all messages that arrive through it and replies through it. An agent can have multiple channels associated with it. A channel, however, belongs to exactly one agent at a time — if you need to switch the agent for a channel, simply update the association.

​
Channel Types

TypeIdentifierNotes
WhatsApp BusinesswhatsappRequires Meta-approved WABA
InstagraminstagramRequires Business profile and linked Page
TelegramtelegramRequires Bot Token from @BotFather
Widget (website)widgetNo external account — generated by Timely

​
Lifecycle

create channel (disconnected)
    │
    ▼
connect (scanning QR / entering token)
    │
    ▼
connected → receives messages → agent processes
    │
    ├── reconnect if dropped → connected
    │
    ▼
disconnect or delete
WhatsApp channels go through a QR code scanning or official number linking flow. The GET /v1/channels/{id}/qr-code endpoint returns the QR code in base64 during the connection window.

​
Main Fields

FieldTypeDescription
idstring (UUID)Unique channel ID
agent_idstring (UUID)Associated agent
typeenumwhatsapp | instagram | telegram | widget
namestringDescriptive name of the channel
statusenumconnected | disconnected | error
phone_numberstringAssociated number (for WhatsApp/Telegram)
usernamestringProfile username (for Instagram/Telegram)
widget_tokenstringPublic widget initialization token
created_atstringISO 8601 creation timestamp
last_connected_atstringISO 8601 last successful connection timestamp

​
Available Endpoints

See the left sidebar for the full list of endpoints in this group. Each endpoint has its own page with request/response schema, cURL/JS/Python examples, and an interactive playground.

​
Next Steps

Your first request

If you haven’t made your first call yet, start here.