Skip to main content
Version: Latest

Setting Up the Telegram Channel

Telegram is the simplest channel to set up: just a Bot Token created by @BotFather, with no third-party approval or OAuth process.

Prerequisites​

Creating the bot​

If you do not have a bot yet:

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Follow the instructions: choose a name and a username (must end in bot)
  4. BotFather will return the Bot Token in the format 1234567890:ABCdefGhIJKlmNoPQRsTUVwxyz

Save this token — you will need it in the next step.

Connecting the channel​

In the Hub Chatt2.me dashboard:

  1. Go to Channels → Activate/Configure → Telegram
  2. Enter the Bot Token obtained from BotFather
  3. Click Connect

The Hub configures the Telegram webhook automatically. The channel UUID will be available after the connection.

Identifying the recipient (to)​

The to field on Telegram is the chat_id — an integer (can be negative for groups) that identifies the conversation.

How to get the chat_id​

The most reliable way is via webhook: when the user sends a message to your bot, the chat_id is in the received payload.

Alternatively, you can use the Telegram API directly:

curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

The chat_id appears in result[].message.chat.id.

Supported content types​

Telegram has one of the most complete sets of message types:

  • Text
  • Image (with optional caption)
  • Video (with optional caption)
  • Audio (with optional caption)
  • Document / file (optional caption, filename and MIME type)
  • Sticker (native WebP, WebM, or TGS media URL)
  • Location (latitude and longitude)
  • Single or multiple contacts
  • Poll via interactive type
  • Message reaction
  • Reply (replying to a specific message)

Media captions​

Add content.text alongside imageUrl, videoUrl, audioUrl, or documentUrl to send a caption in the same message. All four media types support captions, including native voice messages. See the caption support matrix.

Text formatting​

Send formatting through content.text; do not add a provider parse_mode field. The Hub converts supported markers to Telegram HTML: *bold*, _italic_, __underline__, ~strike~, inline code in single backticks, preformatted text in triple backticks, spoilers between two vertical bars, and [label](https://example.com) links. Plain text is escaped during conversion.

{
  "from": "@your_bot",
  "to": "123456789",
  "content": {
    "text": "*Order confirmed*\n_Thank you_ — __details__ and ~old price~. `ABC123`\n[Open order](https://example.com/order)"
  }
}

Contacts and locations​

A single contact uses a native contact card; rich extra fields are attached as a generated vCard. Above 2,048 UTF-8 bytes the single-card vCard is reduced (at most three emails and one address, without URLs/department), and may be truncated further; extra fields may not survive. Multiple contacts become a contacts.vcf document. Use the Hub's flat camelCase contact fields, not raw Telegram/WhatsApp provider fields; see Contact examples.

Coordinates alone use a location card. With a nonempty name or address, the Hub uses a venue, using the supplied value for both venue fields when only one is provided. See Location.

Media formats and limits​

The Hub uploads Telegram media with multipart so it can use Telegram's larger upload limits rather than the smaller remote-URL limits.

TypeFormats currently accepted by the HubOutbound limitInbound download limit
PhotoJPEG, PNG, BMP; static WebP input is converted to PNG10 MB20 MB
AnimationGIF; animated WebP input is converted to silent H.264 MP450 MB20 MB
VoiceMP3/MPEG, M4A/MP4, FLAC, WAV, OGG, Opus, AAC and WebM input normalized to OGG/Opus50 MB20 MB
VideoMP4; MOV/QuickTime, AVI, MKV and WebM input is converted to H.264/AAC MP450 MB20 MB
DocumentAny MIME except SVG, HTML and JavaScript MIME types blocked by the Hub50 MB20 MB
StickerWebP, WebM, TGSWebP: 50 MB transport; WebM: 256 KB; TGS: 64 KB20 MB

audioUrl always uses Telegram's native voice presentation after OGG/Opus normalization. Use documentUrl when the original audio bytes must be delivered as a generic file. Likewise, use documentUrl for a byte-identical MOV, AVI, MKV or WebM file instead of native video presentation. GIF and normalized animated WebP use Telegram's animation presentation rather than a static photo. Voice messages received as OGG/Opus continue through the Hub's existing MP3 conversion so customer webhooks receive a broadly playable audio URL.

Sticker files must also meet Telegram's codec, duration and dimension requirements. The 50 MB WebP value is the multipart transport ceiling, not a promise that an arbitrary image is a valid sticker.

The Telegram Bot API cannot download inbound files larger than 20 MB through getFile. The message metadata can still arrive, but the Hub cannot promise a durable media URL for a larger file. A raw Telegram file URL is never exposed because it contains the bot token.

Sending to groups​

If your bot is added to a group, the group's chat_id is a negative number (e.g. -1001234567890). The bot needs permission to send messages in the group.

Identifying the sender (from)​

In POST /v1/communication/telegram/message, set from to the application channel UUID or the bot username configured for that channel (with or without a leading @). The UUID always works as a fallback. See Sending messages overview.

Next steps​