Channels Reference

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

Type	Identifier	Notes
WhatsApp Business	`whatsapp`	Requires Meta-approved WABA
Instagram	`instagram`	Requires Business profile and linked Page
Telegram	`telegram`	Requires Bot Token from @BotFather
Widget (website)	`widget`	No 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

Field	Type	Description
`id`	string (UUID)	Unique channel ID
`agent_id`	string (UUID)	Associated agent
`type`	enum	`whatsapp` \| `instagram` \| `telegram` \| `widget`
`name`	string	Descriptive name of the channel
`status`	enum	`connected` \| `disconnected` \| `error`
`phone_number`	string	Associated number (for WhatsApp/Telegram)
`username`	string	Profile username (for Instagram/Telegram)
`widget_token`	string	Public widget initialization token
`created_at`	string	ISO 8601 creation timestamp
`last_connected_at`	string	ISO 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.

Delete training List channels

​Concept

​Channel Types

​Lifecycle

​Main Fields

​Available Endpoints

​Next Steps

Your first request

Concept

Channel Types

Lifecycle

Main Fields

Available Endpoints

Next Steps