Telegram

Telegram is by far the simplest channel to set up — there's no Business Manager, no approval queue, no template review. You create a bot in @BotFather, paste the token, and you're live.

Connecting

1. Open Telegram → message @BotFather.
2. Send /newbot. Give it a display name and a _bot-suffixed username.
3. BotFather replies with a Bot Token like 123456789:ABCDef-….
4. In Kinderpedia: Integrations → Telegram → Connect → paste the token.

On save, Kinderpedia calls GET https://api.telegram.org/bot{TOKEN}/getMe to validate. The bot's display name + photo are pulled to populate the integration card.

Webhook setup

After the token validates, Kinderpedia auto-registers the webhook via setWebhook:

POST https://api.telegram.org/bot{TOKEN}/setWebhook
?url=https://<your-domain>/api/integrations/telegram/webhook
&secret_token=<random>

The secret_token is generated per-school and validated server-side on every inbound (X-Telegram-Bot-Api-Secret-Token header). Mismatches are 401'd.

Telegram does not require you to expose your webhook URL anywhere else — only Telegram's servers ever hit /api/integrations/telegram/webhook.

How conversations start

Unlike WhatsApp/WeChat, you cannot "send first" on Telegram. The user must:

1. Find your bot (search @your_bot_username or scan a deep-link QR).
2. Tap Start in the bot's chat.

That click sends a /start command to your webhook. We catch it and create the conversation thread. From then on, your bot can send messages to that user without restrictions.

The start command can carry a payload (/start ref_lead_42) which we use to auto-link the new conversation to a lead.

No 24-hour window

Telegram has no customer-care window. Once a user has clicked Start on your bot, you can message them anytime — no templates, no tags, no approval queue.

That's a double-edged sword: it's the most ergonomic channel for staff, but also the easiest to misuse. The platform-level safeguard is that users can block your bot in one tap, and we get a chat_member update reflecting that — the conversation gets auto-marked as Blocked.

User identity

Telegram exposes a per-bot chat_id which is stable for the lifetime of the user's account. Conversation keys: telegram:<chat_id>. The user's first/last name, username (@handle), and language code are captured to the conversation header.

Note: Telegram may or may not expose the user's phone number — the user has to actively share it via Telegram's "Share Contact" button, which our bot can request. Most parents won't share unprompted; if you need the phone (for SMS fallback or duplicate detection), prompt for it in the welcome message.

Media

Inline support for photos, videos, voice messages, video notes (round videos), documents, stickers, locations, contacts. Telegram's file size caps are generous:

• Photos / videos: 50 MB per file (bot API)
• Documents / audio: 50 MB
• Voice notes: any size that Telegram allows in the client

Inbound files arrive with a file_id. We exchange that for a download URL via getFile and re-host on S3.

Outbound media works the same as other channels — drag-and-drop or paperclip in the composer.

Bot commands

Bots can declare a command list (/help, /info, etc.) via setMyCommands. Kinderpedia ships a sensible default set (/start, /help, /contact) which you can override in Integrations → Telegram → Configure commands. This is what shows up in Telegram's / autocomplete.

Slash-command messages from users come through the webhook the same as any other text message — we surface them in the inbox; staff can handle them however they want.

Groups and channels

A bot can be added to Telegram groups as a member. By default, bots in groups only see messages that mention them (@your_bot) — privacy mode. We don't currently support group conversations in the inbox; group inbounds are dropped.

Channels (broadcast-only) are not supported either — a different API surface entirely.

Common errors

Symptom	Likely cause
"Token invalid" on save	Token revoked / regenerated in BotFather. Get a fresh one.
Sending returns "Forbidden: bot was blocked by the user"	User tapped Block. Auto-mark thread Blocked.
Send returns "chat not found"	User deleted their Telegram account, or chat_id stale.
User scans QR but conversation doesn't appear	They didn't tap Start — Telegram only sends webhook events after the explicit acceptance.

Why Telegram is the easiest first channel

If you're piloting the chat inbox and don't have a Meta Business Manager / WeChat OA ready, Telegram is the fastest path to a working multi-channel setup. Get a token in 60 seconds and ship a QR on your enrolment page.

Related

• Connecting channels
• Conversations
• Blocking