Telegram Integration

This page describes how to connect a SipPulse AI Agent to a Telegram bot using a bot token from BotFather.

1. What is Telegram Integration?

Telegram Integration is a deployment channel that allows you to connect your agent to a Telegram bot. Users can interact with your agent directly through Telegram by sending messages to the bot.

How to Create a Telegram Bot

Before connecting, you need a Telegram bot. Open Telegram, search for @BotFather, and send the /newbot command. Follow the instructions to create your bot and obtain the bot token.

When to Use Telegram

Ideal scenarios:

• Customer support and FAQ automation
• Notifications and alerts delivered via Telegram
• Interactive services accessible from any Telegram client (mobile, desktop, web)
• Quick deployment with no infrastructure requirements

2. Initial Setup

Prerequisites

• A Telegram bot created via @BotFather
• The bot token provided by BotFather
• The bot cannot be connected to another agent

Connect a Bot

1. Navigate to Agents and select the desired agent.
2. Open the Deploy tab and locate the Telegram card.
3. Click Connect.
4. In the modal, paste your bot token (obtained from BotFather).
5. Click Connect to confirm.
6. Once connected, the card will display your bot's @username (linked to Telegram) and the status will change to Online.

One bot per agent

Each Telegram bot can only be connected to one agent at a time. If you try to connect a bot that's already in use, you'll see an error message.

Test Before Deploying

You can test your agent in the Playground before deploying it to Telegram. This helps ensure the conversational flow works as expected.

3. Bot Commands

When the integration is active, your bot supports the following commands:

Command	Description
/start	Starts the bot and sends the configured welcome message
/reset	Resets the current conversation thread and starts fresh
/help	Shows the list of available commands
/auth <code>	Authenticates with an access code (only available in Access Code mode)
/voice	Toggles voice mode — agent replies with audio in addition to text (only available when TTS is configured)

Users can type these commands at any point during the conversation.

4. How It Works in Practice

Message Flow

User sends message → Telegram → SipPulse AI → Agent processes → Response sent to Telegram

When the integration is active, every message sent to your bot is forwarded to the agent for processing. The agent analyzes the message and generates an appropriate response based on its configuration.

The /start Command

When a user starts a conversation with your bot (by sending /start), the bot sends a customizable welcome message. This is configured in the bot's preferences (see Configuration).

The /reset Command

The /reset command closes the user's current conversation thread and starts a new one. This is useful when the user wants to start over without the agent retaining context from the previous interaction.

5. Management

Enable or Disable Quickly

Use the toggle switch on the card to control the integration:

• On — The agent processes incoming messages in real time.
• Off — Incoming messages are ignored; no token charges apply.

Status

The card displays the current status:

Status	Description
Online	Bot is active and processing messages.
Offline	Bot is disabled or not connected.

Options Menu

Click the options menu on the Telegram card to access:

• Preferences — Configure the start message and access control (see Configuration).
• Manage Users — View and manage users who interacted with the bot (see User Management).
• Remove — Disconnect and remove the bot integration entirely.

6. Configuration

Start Message

The start message is sent automatically when a user sends /start to your bot. This is typically the first interaction a user has with your bot.

To configure:

1. Click the options menu on the Telegram card.
2. Select Preferences.
3. Write your welcome message in the text area.
4. Click Save.

TIP

Use the start message to introduce your agent, explain what it can do, and guide users on how to interact with it.

Access Control

Access control determines who can interact with your Telegram bot. Three modes are available:

Open (Default)

Anyone can interact with the agent immediately. Users are automatically approved on first contact. No authentication is required.

Access Code

Users must provide a code to authenticate before they can chat with the agent.

How it works:

1. When an unauthenticated user messages the bot, they receive a prompt: "To access this agent, send: /auth <your access code>"
2. The user sends /auth mycode123
3. If the code is correct, the user is approved and can interact normally
4. If the code is incorrect, the user receives an error and can try again

Configuration fields:

Field	Description	Constraints
Access Code	The code users must provide	8–100 characters
Max Auth Attempts	Number of failed attempts before auto-block	Minimum 1 (optional)
Send Rejection Message	Whether to send feedback to unauthenticated users	Toggle on/off
Rejection Message	Custom message for unauthenticated users	Free text (optional)

If Max Auth Attempts is set and a user exceeds the limit, they are automatically blocked and receive: "You have exceeded the maximum number of attempts. Your access has been blocked."

Whitelist

Only manually approved users can interact with the agent. New users appear as pending and must be approved by an administrator.

How it works:

1. A new user messages the bot
2. They receive a message: "Your access is pending approval. Please wait for administrator authorization."
3. The user appears in the Manage Users table with status Pending
4. An administrator approves or denies the user
5. Once approved, the user can interact normally

Silent Mode

When Send Rejection Message is turned off, unauthenticated or pending users receive no feedback at all — the bot simply does not respond. This can be useful for security-sensitive deployments where you don't want to reveal the bot's existence to unauthorized users.

Language

The bot's system messages (authentication prompts, error messages, etc.) are sent in the configured language. Supported languages: English (en) and Portuguese (pt).

7. User Management

The Manage Users option in the Telegram card's options menu opens a table of all users who have interacted with your bot.

User Table

Column	Description
Name	User's first name from Telegram
Username	Telegram @username (may be empty)
Status	Current access status (see below)
First Seen	Date the user first contacted the bot

User Statuses

Status	Description
Approved	User can interact with the bot
Pending	User has messaged the bot but is awaiting approval (whitelist mode) or hasn't authenticated (access code mode)
Revoked	User's access has been manually removed
Blocked	User was blocked manually or by exceeding the max authentication attempts

Available Actions

Each user row has a context menu with the following actions (visibility depends on current status):

• Approve — Grants access to the user. Available for pending, revoked, and blocked users.
• Deny — Rejects a pending user (changes status to revoked). Only for pending users.
• Revoke — Removes access from an approved or blocked user.
• Block — Permanently blocks a user from interacting with the bot.

Filtering

Use the status filter dropdown to view only users with a specific status (e.g., show only pending users awaiting approval).

8. Voice Features

Your Telegram bot can transcribe voice messages from users and reply with audio. Both features are optional and configured independently in the bot's preferences.

Voice Message Transcription (Audio to Text)

When enabled, voice messages sent by users are automatically transcribed to text and processed by the agent as a regular text message.

How it works:

User sends voice message → Bot transcribes audio → Agent processes text → Sends text response

To enable:

1. Click the options menu on the Telegram card.
2. Select Preferences.
3. In the Audio Transcription section, toggle it on.
4. Select a Transcription Model from the dropdown (available models are shown in the UI).
5. Click Save.

Field	Description
Enabled	Master switch for voice message transcription (default: off)
Transcription Model	The speech-to-text model used to transcribe voice messages

Voice Messages Only

Transcription applies to voice messages recorded directly in Telegram. If transcription is disabled, voice messages are ignored and the user receives a message asking them to send text instead.

TIP

This feature works seamlessly with access control — users must be authenticated before their voice messages are processed.

Voice Responses (Text to Speech)

When enabled, the /voice command becomes available. Users can toggle voice mode to receive audio responses alongside text messages.

How it works:

1. User sends /voice → voice mode is enabled
2. The agent replies with both text and audio for every message
3. User sends /voice again → voice mode is disabled (text only)

Text Is Always Sent

Audio responses are sent in addition to the text message, not as a replacement. Users always receive the text response regardless of voice mode.

To enable:

1. Click the options menu on the Telegram card.
2. Select Preferences.
3. In the Text to Speech section, toggle it on.
4. Select a TTS Model from the dropdown.
5. Select a Voice from the dropdown (voices are filtered by the agent's language).
6. Click Save.

Field	Description
Enabled	Master switch for voice responses (default: off)
TTS Model	The text-to-speech model used to generate audio
Voice	The voice used for audio responses (filtered by agent language)

Both Model and Voice Required

The /voice command only appears in the bot's command menu when both a TTS model and a voice are selected. If either is missing, users won't see the command.

9. Troubleshooting

Invalid Bot Token

If you see an error when connecting, verify that:

• The token was copied correctly from BotFather (format: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
• The bot has not been deleted or revoked in BotFather.

Bot Already in Use

If the bot is already connected to another agent, you need to either:

• Remove the bot from the other agent first, or
• Create a new bot via BotFather.

Bot Not Responding

If the bot is connected but not responding to messages:

• Check that the toggle switch is On (not disabled).
• Verify the agent has proper instructions configured.
• Test the agent in the Playground to ensure it responds correctly.

User Blocked After Too Many Attempts

If a user is blocked because they exceeded the max authentication attempts:

1. Open Manage Users from the Telegram card options menu.
2. Find the blocked user in the table.
3. Click the context menu and select Approve to restore access.

Users Stuck as Pending

In Whitelist mode, users require manual approval:

1. Open Manage Users from the Telegram card options menu.
2. Find pending users in the table.
3. Click Approve or Deny for each user.

Voice Messages Not Being Transcribed

If users send voice messages but the bot doesn't respond:

• Verify that Audio Transcription is enabled in Preferences.
• Ensure a Transcription Model is selected.
• Check that the user is authenticated (access control applies before transcription).

/voice Command Not Appearing

If users can't see the /voice command:

• Verify that Text to Speech is enabled in Preferences.
• Ensure both a TTS Model and a Voice are selected — both are required for the command to appear.