Telegram configuration guide

Add a Telegram Bot instance in MOI to store your Bot Token and optional Webhook verification secret. This guide explains how to sign in to Telegram, obtain a Bot Token through BotFather, create an instance in MOI, and test the connection.

Prerequisites

  • A Telegram account for creating and managing bots.

  • Confirm that your MOI workspace and deployment profile expose the Telegram configuration entry and allow adding instances (public SaaS deployments may hide new configuration entries for Telegram, while private or enabled deployments expose it under Connectors or Channel Management).

  • Confirm that your browser can access Telegram and that the MOI service can reach the Telegram Bot API. Signing in from your browser does not establish server-side network reachability.

1. Sign in to Telegram

Open Telegram Web. If you are already signed in on your phone, open Settings > Devices > Add Device in the mobile app and scan the QR code shown on the web page to confirm sign-in.

You can also click LOG IN BY PHONE NUMBER and follow the prompts, or click 使用简体中文继续 if switching interface languages.

Telegram Web login page showing QR code, phone number, and Passkey login options (Chinese UI preview).

Sign in using the QR code on Telegram Web; screenshot is for locating the login entry.

2. Create a bot and obtain the Bot Token

  1. Open the official BotFather page and verify that the username is @BotFather with the verification badge.

Official Telegram BotFather page showing the verification badge, @BotFather handle, and START BOT button.

Create and manage bots through the official BotFather account.

  1. Click START BOT to open a chat with BotFather in Telegram. In Telegram Web, you can also sign in first and search for @BotFather.

  2. Send /newbot in the BotFather conversation.

  3. Enter a display name for the bot when prompted, such as MOI Notice.

  4. Enter a bot username when prompted, such as example_moi_notice_bot. The username must be unique, 5–32 characters long, contain only letters, digits, and underscores, and end with bot. If the username is taken, enter a different one.

  5. After creation succeeds, copy the Bot Token from BotFather’s reply and record the bot’s username or link for verification.

The Bot Token is the credential used to call the bot. A display name, @username, or personal login verification code cannot replace it. Enter the token only in MOI’s Bot Token field—do not place it in descriptions, prompts, or public screenshots.

3. Create a Telegram instance in MOI

  1. Open Channel Management (or the corresponding Connectors entry in your deployment), then select Telegram under Communication.

  2. In the instance list, click Add to open the bot message and Webhook configuration form.

MOI Telegram configuration form containing instance name, Bot Token, description, Webhook Secret, and connection timeout (Chinese UI labels).

Enter the Bot Token issued by BotFather and expand advanced settings if needed.

  1. Complete the fields below. Description, Webhook Secret, and Connection Timeout (seconds) are located under advanced settings.

Field

Required

Instructions

Instance Name

Yes

Choose a name such as Telegram Project Notice to distinguish instances in MOI. It does not need to match the bot’s display name.

Bot Token

Yes

Paste the full token issued by BotFather. Do not enter the bot username or prepend bot to the token.

Description

No

Describe the purpose of the instance, such as Project test notifications.

Webhook Secret

No

A verification secret you define separately from the Bot Token. Incoming requests from Telegram must send the same value as secret_token.

Connection Timeout (seconds)

No

Used for connection tests and tool invocations. Leave empty to use the 30-second default; maximum is 300 seconds.

Webhook Secret corresponds to the Telegram Bot API secret_token: 1–256 characters using only A-Z, a-z, 0-9, _, and -. Telegram includes this value in the X-Telegram-Bot-Api-Secret-Token header so MOI can verify callback requests.

  1. Click Save. Return to the instance list and confirm that the new instance appears with the expected name.

Note

This form saves the instance credentials in MOI. Entering a Webhook Secret does not register a Webhook with Telegram or confirm incoming event delivery; test the connection separately after saving.

4. Test the connection and verify settings

  1. In the Telegram instance list, click Test Connection for the new instance (or open its detail view and click Test Connection).

  2. Wait for the result. A passing check shows a connection-test-passed prompt and updates the Last Checked result and timestamp in the list.

  3. Open instance details to verify the name and connection timeout. To update settings, click Edit, save, and run the connection test again.

A passing connection test verifies connectivity with the saved credentials. It does not prove that messages have been delivered or Webhook events are flowing; verify actual delivery in Telegram and event processing in MOI separately.

5. Maintain instances and tokens

To rotate a Bot Token, edit the instance under Telegram, enter the new token, save, and test the connection again. Do not judge token validity by whether masked sensitive fields appear in plain text; rely on the connection test result.

If a Bot Token is lost or compromised, use /token in BotFather to generate a new token for the bot, then update the corresponding MOI instance.

When an instance is no longer needed, verify its name in the list, choose Disconnect, and confirm. Disconnecting an instance in MOI and deleting the bot in Telegram are independent operations.

FAQ

Issue

Resolution

Cannot sign in via Telegram Web

If already signed in on mobile, scan the QR code from Settings > Devices > Add Device; otherwise choose LOG IN BY PHONE NUMBER and complete verification.

Clicking START BOT does not open a chat

Sign in to the Telegram desktop/web app first, then search for the verified @BotFather handle.

BotFather rejects the bot username

Verify the username is unused, 5–32 characters long, ends with bot, and uses only ASCII letters, digits, and underscores.

Connection test fails after saving

Check the error details to confirm the full token matches the target bot and was not rotated, and verify that the MOI server can reach the Telegram Bot API.

Unsure where to get Webhook Secret

You define it yourself; it is not returned by BotFather. Set it only when validating Webhook callbacks and keep both sides identical.

Still fails after raising timeout

Raising the timeout does not fix an invalid token. Distinguish authentication errors from network timeouts before adjusting settings.

Last updated on