Channel metadata for a public Telegram channel or group: title, description, avatar, verified badge, the live subscriber string and the public preview link.
Only public channels render a preview. A personal profile and a handle that does not exist return the same contact page, so is_public_channel_preview answers whether the handle renders as a channel — not whether a user account exists.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
1 required parameter needed before sending a request.
string
Required
Public channel handle. A bare handle or an @handle also works in the path; use this parameter for the host forms, which contain a slash: t.me/telegram, t.me/s/telegram, https://t.me/s/telegram, https://telegram.me/telegram, https://telegram.dog/telegram. Every form normalises to the bare lowercase handle, because Telegram usernames are case-insensitive, and no request is ever issued to a mirror host.
When this parameter is present it is the handle that is used; the path segment is only the fallback for the forms that fit there.
example
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"channel": {
"title": "Telegram News",
"username": "telegram",
"avatar_url": "https://cdn.example/avatars/telegram.jpg",
"description": "The official Telegram on Telegram. Much recursion.",
"is_verified": true,
"preview_url": "https://t.me/s/telegram",
"permalink_url": "https://t.me/telegram",
"subscribers_raw": "9 401 414 subscribers",
"is_public_channel_preview": true
}
},
"meta": {
"attempts": 1,
"duration_ms": 812
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
The username, post id or search query failed validation. A 422 carries a message and an errors map, and no error code.
{
"errors": {
"username": [
"The username may only contain letters, digits and underscores."
]
},
"message": "The request validation failed"
}Upstream Unavailable
No usable page came back. The request did not consume a credit. The code varies by failure type: UPSTREAM_HTTP_ERROR when the target answered with a non-successful status, TELEGRAM_DISABLED while the surface is switched off, TRANSPORT_ERROR when every gateway failed to connect, and a generic upstream_unavailable when no connection was available at all.
{
"error": {
"code": "UPSTREAM_HTTP_ERROR",
"message": "Telegram did not return usable data. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.