POST /channels — Join a Telegram Channel by Username

This endpoint sends a JoinChannelRequest via Telethon to add the authenticated account to the specified public channel. On success it returns the full channel object for the channel that was just joined.

Endpoint

POST /channels

Authentication

Requires an active Telethon session on the server. Unlike GET /channels, this endpoint always uses the real Telegram client — FakeClient is never used regardless of the API_ID setting.

Query Parameters

channel_name

string

required

The public username of the Telegram channel to join, without the leading @ (e.g. durov, telegram). Must resolve to a valid, accessible public channel.

Request Body

None.

Response

data

Channel

required

The full channel object for the channel that was joined.

Show Channel object properties

integer

required

Unique channel identifier assigned by Telegram.

title

string

required

Display name of the channel.

date

string

required

ISO 8601 datetime string representing the channel creation date.

username

string | null

Public @username of the channel.

participants_count

integer | null

Total number of members. May be null if Telegram does not expose the count.

broadcast

boolean | null

true if this is a one-way broadcast channel.

megagroup

boolean | null

true if this is a supergroup.

verified

boolean | null

true if the channel carries Telegram’s official verification badge.

scam

boolean | null

true if Telegram has flagged this channel as a scam.

creator

boolean | null

true if the currently authenticated account is the creator of this channel.

left

boolean | null

true if the currently authenticated account has left this channel.

noforwards

boolean | null

true if forwarding messages out of this channel is restricted.

forum

boolean | null

true if the channel has forum/topics mode enabled.

All remaining fields map directly to the Telethon constructor documented at https://tl.telethon.dev/constructors/channel.html.

Status Codes

Status	Description
`201 Created`	The authenticated account successfully joined the channel. The full channel object is returned.
`400 Bad Request`	The channel username was not found or is invalid. Raised from a `ValueError` returned by Telethon.
`429 Too Many Requests`	Telegram’s flood-wait protection was triggered. The `detail` field contains the number of seconds to wait before retrying.

Examples

curl -X POST 'http://localhost:5004/channels?channel_name=durov'

Telegram enforces strict rate limits on join operations. If you receive a 429 Too Many Requests response, inspect the detail field — it contains the number of seconds you must wait before issuing another join request. Repeated violations can result in longer temporary bans from the Telegram API.

Authentication

Channels

Messages

POST /channels — Join a Telegram Channel by Username

Endpoint

Authentication

Query Parameters

Request Body

Response

Status Codes

Examples

Build docs developers (and LLMs) love

Authentication

Channels

Messages

Documentation Index

​Endpoint

​Authentication

​Query Parameters

​Request Body

​Response

​Status Codes

​Examples

Build docs developers (and LLMs) love

Endpoint

Authentication

Query Parameters

Request Body

Response

Status Codes

Examples