Telegram Integration

Connect your agent to Telegram and let users chat with it directly in the Telegram app.

Overview

Telegram integration provides:

• Live streaming replies (Bot API 9.5 sendMessageDraft with edit-message fallback)
• Voice messages transcribed automatically with Whisper
• MarkdownV2 formatting that renders cleanly every time
• Deep-link campaigns with custom welcome and suggested replies
• One-tap emoji reactions with sentiment classification
• Built-in slash commands (/start, /help, /reset, /new)
• Direct messages and group chats (per-user sessions in groups)
• A built-in in-bot Storefront — multipage product catalog, per-product AI chat, and lightweight order-taking, all inside Telegram (free on every plan)
• Optional Telegram Business co-pilot for Premium users (separate integration)
• Saba on Telegram for operators (separate integration)

Prerequisites

• A Telegram account
• BotFather access (Telegram’s bot creation tool)

Setup Steps

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts:
   • Enter a name for your bot (e.g., “My Support Bot”)
   • Enter a username (must end in “bot”, e.g., “mysupportbot”)
4. BotFather will give you a Bot Token — save this securely

2. Connect to Cuneiform Chat

1. Go to Integrations in the sidebar
2. Open the Telegram card
3. Paste your Bot Token
4. Click Connect

3. Configure Your Bot

Optional bot settings via BotFather:

• /setdescription — What the bot does
• /setabouttext — Information in the bot profile
• /setuserpic — Profile picture for your bot

4. Test Your Bot

1. Find your bot in Telegram by searching its username
2. Start a conversation with /start
3. Send a message and verify you get a response

How It Works

User sends message → Telegram → Cuneiform Chat → Agent processes → Response sent back

Messages are processed in real-time. The agent searches your content and generates responses based on your configuration.

Features

Live streaming replies

The bot’s reply lands within milliseconds and grows in place as your agent thinks — using Telegram’s native sendMessageDraft (Bot API 9.5) where supported, with a throttled edit-message fallback elsewhere. No more 5–15 seconds of silence between question and answer.

Voice messages

Voice notes sent to the bot are transcribed via Whisper and answered as if they’d been typed. Language is auto-detected from the conversation, so short clips in any language stay accurate. Caps at 2 minutes per note. Available on every plan, including the free trial.

MarkdownV2 formatting

Bold, italics, code blocks, lists, and links render exactly as your agent intended — no broken markdown or stray asterisks. Escaping is centralized in the platform so every reply stays clean. MarkdownV2 is the default; HTML mode is available per integration if needed.

Deep links and referral campaigns

Generate t.me/your-bot?start=your-code links from the integration card. Each code can carry a custom welcome message and up to three suggested replies. Click-through, unique users, and conversation conversion are tracked per code — useful for ad campaigns, QR codes, and multi-channel attribution.

One-tap emoji reactions

Users react to bot messages with 👍, ❤, 😡, or any emoji. The bot acknowledges with the right tone via short reaction-acknowledgement replies. A built-in classifier maps any emoji to a positive, negative, or neutral signal you can analyze later. Currently active in DMs.

Slash commands

The integration registers a default command list with Telegram on connect, so users see /start, /help, /reset, and any custom commands you author in Telegram’s native autocomplete menu. /start, /help, /reset, and /new are handled inline at zero AI cost. Drag to reorder; up to 32 entries.

Direct messages

Users chat with your bot one-on-one for private support conversations. Each user has their own session.

Group chats

Add your bot to group chats:

1. Add the bot to a group
2. Make it an admin (for full message access — see Group Privacy below)
3. Users mention the bot (@your_bot) or reply to its messages

Each user in a group has their own conversation thread — the bot doesn’t mix sessions across members. Forum-topic groups are supported; threads stay scoped to their topic.

In-bot Storefront

Every Telegram bot you connect comes with a built-in Storefront — a polished, multipage in-bot website that opens inside Telegram when end users tap the menu button next to the chat composer. Product cards, galleries, videos, themed pages, per-product AI chat, and lightweight order-taking that hands off to a real human in your inbox — all without an app install or a separate website.

Auto-wired on connect: the chat-menu button opens the storefront, labeled “Shop” if you publish a product or “Open” otherwise. Available on every plan including the free trial.

The full feature guide — composer, blocks, themes, per-product chat, order CTAs, tier limits — lives on a dedicated page:

→ Telegram Storefront for the complete setup, block reference, and customer flow.

A small Help Center support panel is pinned at the end of the storefront’s page menu for ad-hoc FAQ + ask-the-bot shortcuts. Most storefronts don’t lean on it heavily — products and order CTAs answer buying-flow questions on the storefront itself. Author entries from the bot card’s three-dot menu → Help Center (up to ~50 entries, drag-to-reorder, ~5 minute server cache).

Telegram Business co-pilot

Premium-tier Telegram users can have your bot answer DMs on their personal account via Telegram’s Business mode. The bot replies through the Premium user’s business_connection_id, so contacts see what looks like the Premium user’s own replies — useful for founders, creators, and small teams who get DM’d on their personal accounts all day.

Setup is a separate integration in the admin panel (“Telegram Business co-pilot”). Key invariants:

• 1 bot = 1 customer agent. A Telegram bot can only point at one webhook at a time — you can’t share a bot with the regular Telegram integration or Saba on Telegram. Create a fresh BotFather bot for Business mode.
• BotFather Business Mode toggle is required. Without it, Premium users see “this bot doesn’t support Telegram Business yet” when adding it. Toggle it on under Bot Settings → Business Mode.
• N Premium users per integration. Each links once via /start <code> in a regular DM with the bot.
• DMs only. Business connections don’t cover group chats.
• Manual takeover is automatic. When the Premium user types a reply themselves, the bot pauses on that chat for a sliding window so it doesn’t talk over a live conversation.
• Connection-level kill switch. Toggle “Disable auto-reply” on the integration card to pause the bot across every linked Premium user without disconnecting.

See Connect Business bot under the Telegram Business co-pilot section of the admin panel Integrations page for the full setup playbook.

Saba on Telegram

Operators can also chat with Saba (the platform assistant) from a dedicated Telegram bot. Same permissions and data access as the admin panel — useful when you’re away from your laptop and need to check agent stats, billing, or recent activity.

Two surfaces over the same channel:

• DM bot — text replies in a regular Telegram DM, with inline action buttons that deep-link back to the right admin-panel page (?from=saba_telegram for attribution).
• Saba Mini App — a richer chat surface inside Telegram at saba-mini.cuneiform.chat with conversation history, tool-call detail, browser voice input, and markdown export. Every DM reply ships with an “Open in Mini App” inline button to switch surfaces mid-conversation.

Setup is admin-side: connect a fresh BotFather bot under “Saba on Telegram” in Integrations. Each org member then links their personal account with a 10-minute code.

See Platform Assistant → From Telegram for the user-side experience.

Bot Commands

You can configure custom commands via BotFather:

Troubleshooting

Bot Not Responding

1. Verify the bot token is correct
2. Check the integration is connected in Cuneiform Chat
3. Ensure your agent is properly configured
4. Test the agent in Playground first

Token Issues

If you need a new token:

1. Go to BotFather
2. Send /mybots → Select your bot → API Token → Revoke
3. Update the new token in Cuneiform Chat

Group Chat Issues

• Ensure the bot has admin permissions
• Check privacy mode settings via BotFather (/setprivacy)

Security

• Bot tokens are encrypted and stored securely
• Conversations are processed through secure connections

Disconnecting

To remove the Telegram integration:

1. Go to Integrations in the sidebar
2. Open the Telegram card and click Disconnect

This stops the bot from responding but doesn’t delete the Telegram bot itself. Delete via BotFather if needed.