Unified.to
All articles

How to set up Telegram (bot) with Unified.to

June 30, 2026

Telegram's Bot API lets you send and receive messages through a bot account you control. This guide walks you through creating a Telegram bot, connecting it to Unified.to with its bot token, and (optionally) turning on webhooks so you receive incoming messages and button clicks in real time.

Estimated time: 10 minutes

Prerequisites

  • A Telegram account (any mobile or desktop client).
  • A Unified.to account with a workspace. Sign up here if you don't have one.
  • For receiving messages via webhooks: nothing extra — Unified.to hosts the HTTPS endpoint for you.

Bot API vs. personal account: This integration uses the Telegram Bot API, so all messages are sent and received as your bot, not as your personal Telegram user. People interact with your bot by starting a chat with it or by adding it to a group/channel.

Step 1 — Create a bot and get your bot token

  1. In any Telegram client, open a chat with @BotFather (the official bot for creating bots).
  2. Send the command /newbot.
  3. When prompted, enter a name for your bot (the display name, e.g. Acme Support).
  4. Then enter a username for your bot. It must end in bot (e.g. acme_support_bot).
  5. BotFather replies with a confirmation that includes your HTTP API token. It looks like this:
    123456789:AAEhBP0...M_zv1u123ew11
  6. Copy this token and keep it safe — it grants full control of your bot. You'll paste it into Unified.to in Step 3.

Lost the token later? Send /token to BotFather and pick your bot, or /revoke to roll it.

Step 2 — (Optional) Let your bot read group messages

By default a bot in privacy mode only receives messages that mention it or reply to it. If you want your bot to receive all messages in a group:

  1. Open @BotFather and send /setprivacy.
  2. Select your bot.
  3. Choose Disable.

You can skip this step for one-to-one (direct) chats — bots always receive direct messages sent to them.

Step 3 — Connect Telegram in Unified.to

  1. In the Unified.to dashboard, go to Integrations and search for Telegram (bot).
  2. Click Connect (or Authorize) to start a new connection.
  3. When prompted for credentials, paste the value from Step 1 into the Bot Token field.
  4. Submit. Unified.to validates the token by calling the Telegram getMe endpoint and, on success, creates the connection. The bot's name is shown on the connection.

You can also create the connection programmatically by storing the bot token as the connection's token credential — see the Authorization API.

That's it for sending messages. To receive messages, continue to the webhook setup below.

Step 4 — Find a chat ID to send to

The Bot API can't list chats, so you need the chat ID of whoever you want to message. A chat ID is a number (e.g. 123456789 for a person, or a negative number like -1001234567890 for a group/channel).

The easiest way to discover one:

  1. From the recipient's Telegram account, start a chat with your bot (search its @username and press Start), or add the bot to your group/channel.
  2. Have them send any message to the bot / group.
  3. That inbound message arrives through your Unified.to webhook (Step 5) and includes the channel_id (the Telegram chat ID). Use that value as the destination for future messages.

Sending a message

Once you have a channel_id, send a message through the unified messaging_message endpoint:

curl -X POST 'https://api.unified.to/messaging/<CONNECTION_ID>/message' \
  -H 'Authorization: Bearer <YOUR_UNIFIED_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
        "channels": [{ "id": "123456789" }],
        "message": "Hello from Unified.to 👋"
      }'

You can also include inline buttons (mapped to Telegram inline keyboards) and reply to a message via parent_id. The response contains the new message id, which is required to edit (editMessageText) or delete (deleteMessage) it later.

Step 5 — Set up a webhook to receive messages

Unified.to registers the Telegram webhook for you — you don't call setWebhook yourself. When you create a webhook subscription, Unified.to points your bot at a secure HTTPS endpoint and verifies every delivery with a secret token.

  1. In the Unified.to dashboard, open your Telegram (bot) connection and go to Webhooks (or use the Webhook API).
  2. Create a webhook and choose what you want to receive:
    • messaging_message, event created — each new incoming message (and updated for edited messages).
    • messaging_event, event created — incoming messages and inline-button clicks, delivered as unified events (MESSAGE_RECEIVED, BUTTON_CLICK).
  3. Provide your destination URL — the place Unified.to should forward normalized events to.
  4. Save. Unified.to calls Telegram's setWebhook behind the scenes and begins forwarding events.

Example webhook creation via the API:

curl -X POST 'https://api.unified.to/unified/webhook' \
  -H 'Authorization: Bearer <YOUR_UNIFIED_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
        "connection_id": "<CONNECTION_ID>",
        "object_type": "messaging_message",
        "event": "created",
        "hook_url": "https://your-app.example.com/telegram/incoming"
      }'

To stop receiving events, delete the webhook. Unified.to removes the bot's Telegram webhook automatically once the last subscription on the connection is gone.

Notes & troubleshooting

  • One webhook per bot. Telegram allows a single webhook URL per bot, so all of a connection's webhook subscriptions share the same registration — that's expected and handled automatically.
  • HTTPS is required. Telegram only delivers updates to HTTPS endpoints. Webhooks therefore work on Unified.to's hosted environment but not against a plain-HTTP localhost listener during local development.
  • No history. The Bot API cannot list or fetch past messages or chats — a bot only sees messages sent after it joined a chat, delivered via webhooks. There is no "list messages" or "list channels" operation.
  • Not seeing group messages? Make sure you disabled privacy mode (Step 2) and re-added the bot to the group if needed.
  • getMe / connection fails? Double-check the bot token was pasted exactly, with no extra spaces, and that the bot hasn't been revoked in BotFather.

What you can do next

  • Send, edit, and delete messages (sendMessage, editMessageText, deleteMessage).
  • Look up a single chat's details with messaging_channel (getChat).
  • Receive incoming messages and inline-button clicks via messaging_message and messaging_event webhooks.

Need help? Contact Unified.to support or browse the other guides.

All articles