Skip to main content
Use this guide to create a Telegram bot through BotFather, copy its token, and connect it under Settings → Integrations → Gateways.
Alter connects to Telegram with a bot token from @BotFather. Alter uses long polling on your Mac — you do not configure webhooks or a public URL.

​
Before you start

  • A Telegram account.
  • Alter installed and running on your Mac.
  • The Telegram app or Telegram Web.
Official references:

​
Step 1 — Create a bot with BotFather

1

Open BotFather

In Telegram, open @BotFather and tap Start (or send /start).
Telegram search results showing @BotFather
Source: kitob-bot README
2

Run /newbot

Send /newbot. BotFather asks for a display name (shown in contacts) and a username (must end in bot, for example MyAlterHelperBot).
Telegram chat with BotFather after sending /newbot
BotFather asking for a bot username ending in bot
Source: kitob-bot README
3

Copy the HTTP API token

When creation succeeds, BotFather sends a message containing your token (format like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz). Copy the full string.Telegram documents this flow in the Bot tutorial — Obtain your bot token.
BotFather success message with bot link and HTTP API token
Source: kitob-bot README. The token shown is from a public tutorial repo — treat your own token like a password.
Treat the token like a password. If it is exposed, open BotFather and send /revoke for that bot, then paste the new token into Alter.

​
Optional BotFather settings

​
Step 2 — Start a chat with your bot

1

Open the bot

Tap the link BotFather provides (for example t.me/YourBotName) or search for your bot’s username in Telegram. The success message in Step 1 includes this link.
2

Tap Start

Send /start so Telegram opens a conversation. You need an active chat before testing Alter.

​
Step 3 — Optional: use the bot in a group

Alter can receive messages from group chats as well as private chats.
1

Add the bot to a group

In your group, add the bot as a member (you may need admin permission to add bots).
2

Check Group Privacy (if messages are missing)

By default, Telegram bots in groups may only see commands and @mentions. For broader group access, open @BotFather → /mybots → your bot → Bot Settings → Group Privacy → Turn off.See Bot FAQ — privacy mode.
3

Restrict access if needed

If the bot should only respond to certain people or groups, see Secure access — allowlists and IDs below and fill in Allowed Telegram user or chat IDs when you connect Alter.

​
Secure access — allowlists and IDs

Restrict who can use your Telegram gateway with Allowed Telegram user or chat IDs in Settings → Integrations → Gateways. Alter checks every incoming message and inline-button tap against that list before running an action.
Alter matches user IDs, chat IDs, and @usernames (case-insensitive). Leave the field empty to allow anyone who can message the bot. Enter * to allow everyone explicitly. Messages from users or chats not on the list are silently ignored — Alter does not reply with an error.

​
User ID vs chat ID

Telegram uses numeric IDs for both people and conversations: In a private chat with your bot, the chat ID is usually the same as your user ID. In a group, add the group’s chat ID if you want everyone in that group to be allowed (subject to Group Privacy settings). Alter also accepts @username values (for example @sam) if the person has a public username.

​
How to find your Telegram user ID

1

Use an ID bot (easiest)

In Telegram, open @userinfobot or @getidsbot and tap Start. The bot replies with your numeric Id — that is your user ID.Copy the number (digits only, no @) into Allowed Telegram user or chat IDs.
2

Forward a message (groups or other chats)

To identify someone else, forward one of their messages to @userinfobot or @getidsbot. The bot reports the sender’s user ID.
Only forward messages in contexts where you are comfortable sharing metadata with a third-party bot. For sensitive groups, prefer the Bot API method below or add the whole group by chat ID instead.

​
How to find a chat ID

1

Private chat with your bot

Your user ID from Step 1 above is usually enough — private chat IDs match the user’s ID.To confirm, message your bot, then call Telegram’s getUpdates method with your bot token and look for "chat": {"id": …} and "from": {"id": …} in the JSON. See Telegram Bot API — Chat and User.
2

Group or supergroup

Add @getidsbot to the group temporarily (or use @RawDataBot), send any message in the group, and copy the Chat ID from the bot’s reply. Group IDs are negative numbers.Remove the ID bot from the group when you are done if you do not need it there permanently.
3

Bot API getUpdates (no extra bots)

With your bot token, open this URL in a browser (replace TOKEN with your token):https://api.telegram.org/botTOKEN/getUpdatesSend a test message in the chat you want to identify, refresh the page, and read message.chat.id (chat ID) and message.from.id (sender user ID) from the latest entry.
Treat the URL like a password — anyone with it can control your bot. Close the tab when finished and never share the link.
Alter’s /status command shows the default action and whether a conversation is selected — it does not print user or chat IDs. Use the methods above when building an allowlist.

​
Configure the allowlist in Alter

1

Collect IDs

Gather comma-separated user IDs, chat IDs, and/or @usernames for everyone (or every group) that should be able to use the bot.
2

Paste into Gateways settings

Open Settings → Integrations → Gateways, edit your Telegram gateway, and enter the values in Allowed Telegram user or chat IDs (for example 123456789, -1001234567890, @sam).
3

Save and test

Click Save and restart. Message the bot from an allowed account or group — you should get a reply. Messages from IDs not on the list are ignored with no response.

​
Security best practices

  • Treat the bot token like a password. Store it only in Alter (Keychain). If it leaks, revoke it in @BotFather with /revoke and paste the new token into Alter.
  • Use an allowlist for personal bots. An empty allowlist means anyone who discovers your bot can message it while Alter is running.
  • Prefer numeric IDs over @username. Usernames can change; numeric IDs are stable.
  • Limit group exposure. Turn Group Privacy on in BotFather unless the bot must read all group messages. Add only trusted groups, and allowlist the group chat ID if the bot is in multiple groups.
  • Be cautious with third-party ID bots. They can see forwarded messages and group metadata. Remove them from sensitive groups when you no longer need them.

​
Connect in Alter

1

Open Gateways settings

Open Settings (⌘,) → Integrations → Gateways.
2

Add a Telegram gateway

Click Add gateway → Telegram.
3

Fill in Connection fields

A Telegram gateway setup guide link at the bottom of the Connection section opens this page in your browser.
4

Choose Default action

Ask Anything is the default and works on Telegram out of the box. For a custom action, set Availability to Telegram or All under Action Editor → Gateways.
5

Enable and save

Turn Enabled on, then click Save and restart. Wait for Connected as @your_bot_username.
If connection fails, see Gateways troubleshooting.

​
Test the bot

1

Confirm Alter is running

Gateways only work while Alter is open on your Mac.
2

Send /help

In your Telegram chat with the bot, send /help. The bot should list commands.
3

Send a message

Send a normal message. Alter should show Thinking…, then stream the reply. In private chats, Alter uses Telegram’s native draft preview when available; otherwise it edits a regular message (rich replies can be up to about 32,000 characters).
4

Try buttons and /stop

Send /help and use the New chat, Choose action, or Past chats buttons. While Alter is responding in a group, tap Stop or send /stop to cancel the current turn.
5

Try attachments

Send a photo or document. Alter downloads supported attachments for the turn and can upload output files from tool runs when the action produces them.
6

Try voice messages

Send a voice message or audio file. Alter transcribes it with your selected voice processor (Settings → Voice) and sends the text to the active action. Audio-only messages work as chat turns even without typed text.