Telegram Setup

This guide helps you bind your agent to Telegram in Spira AI using a Telegram bot token.

Spira AI connects to Telegram through the Telegram Bot API. The official Telegram channel guide also notes that direct messages are the default onboarding path, while group behavior depends on bot visibility and mention settings.

Before You Start

You have a Telegram account
You can chat with @BotFather in Telegram
You already created the AI Influencer you want to connect in Spira AI

What You Need

Telegram Bot Token
Example: 123456789:AAExampleBotToken

Setup Steps

1. Create a Telegram Bot in BotFather

Open Telegram and start a chat with @BotFather.

Make sure the handle is exactly @BotFather, then run:

/newbot

Follow the prompts to set:

A display name for the bot
A unique bot username that ends with bot

When BotFather finishes, it will return a bot token. Copy that value and keep it safe.

2. Review Optional BotFather Settings

Depending on how you want the agent to behave, these BotFather settings are often useful:

/setjoingroups to allow or deny adding the bot to Telegram groups
/setprivacy to control whether the bot can see all group messages

Telegram bots usually start with Privacy Mode enabled. With Privacy Mode on, the bot may only receive limited group messages.

If you want the bot to react to normal group messages instead of only explicit mentions or commands:

Disable privacy mode with /setprivacy
Or make the bot a group admin

After changing privacy mode, remove the bot from the group and add it again so Telegram applies the new setting.

3. Bind Telegram in Spira AI

Open the AI Influencer in Spira AI and go to the Agent page.

Then:

Select Telegram as the channel type.
Paste the Telegram Bot Token.
Save the configuration.

How Telegram Behavior Works

Direct Messages

Telegram direct messages are the safest way to start using the bot. This matches the official Telegram channel guidance, where DM access is the default onboarding path.

Group Messages

In groups, Telegram behavior depends on the bot's visibility settings.

Keep these points in mind:

Bots commonly require an explicit @botusername mention before responding in groups
If your workflow expects replies without mentions, privacy mode must allow full group visibility
Making the bot a group admin can also help it receive full group traffic

If the bot seems correctly connected but stays silent in a group, privacy mode is usually the first thing to check.

Recommended Checks Before Save

Confirm you copied the bot token, not the bot username
Confirm the handle you used was exactly @BotFather
Confirm there are no extra spaces or line breaks in the token
Confirm the bot is allowed in groups if you plan to use Telegram groups
Confirm privacy mode matches the group behavior you expect

Common Pitfalls

Copying the bot username instead of the bot token
Using an outdated token after regenerating it in BotFather
Expecting the bot to read all group messages while Privacy Mode is still enabled
Changing privacy mode but forgetting to remove and re-add the bot to the group
Assuming a successful DM setup automatically means group behavior is fully enabled

The bot was added to the correct group
@botusername mention behavior matches your expectations
Privacy mode was configured correctly through /setprivacy
The bot was removed and re-added after privacy mode changed
The bot has group admin status if your setup depends on full group visibility

The Bot Does Not Respond to Non-Mention Messages

This usually means Telegram is still limiting what the bot can see in the group.

Try this:

Open @BotFather
Run /setprivacy
Disable privacy mode for the bot
Remove the bot from the group
Add it to the group again

Telegram