Using Telegram with SoAI

A Telegram bot can send messages to SoAI and return the replies in Telegram. Each Telegram chat becomes a messaging conversation in Chat and uses the model, workspace, sender access, and tools saved with the account.

Prepare Telegram and SoAI

  1. In Telegram, search for and open the verified @BotFather account. Run /newbot and follow the prompts, or select an existing bot, then copy its bot token.
  2. Create a private webhook secret between 16 and 256 characters. Use letters, numbers, hyphens, or underscores. You will enter this value in SoAI; you do not need to register the webhook yourself.
  3. Confirm that the SoAI server has a public HTTPS address. In the SoAI WebUI, an administrator with Configuration changes (CONFIG_PATCH) selects the Settings button at the right of the header, chooses Settings, selects Advanced in the page header, opens Server, sets Public Origin, and selects Save. The setting is SERVER.PUBLIC_ORIGIN.

The public origin must be an HTTPS address whose Telegram callback route is reachable from the internet. If a reverse proxy handles TLS, finish that routing first. Enter the base address without a Telegram webhook path; SoAI builds and registers the callback. The rest of the SoAI interface can remain private when you follow the selective callback routing in Network and TLS. Keep the bot token and webhook secret private.

Telegram requires the callback route to be public, not the complete SoAI WebUI or API. Exposing SoAI directly to the public internet is not recommended. Review Security hardening before enabling this integration.

The Messaging tab requires the SoAI permissions named Model read access (MODEL_READ), Public inference API access (OPENAI_API), and MCP usage (MCP_USE). These permissions do not require an external OpenAI account or API key. SoAI also needs an available model and the MCP tool catalog before Add account can open. Ask an administrator to review your access if the tab is missing.

Add Telegram in SoAI

  1. In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, then select Messaging.
  2. Select Add account.
  3. Enter an Account label, choose Telegram as the Provider, and select the language for SoAI's built-in provider messages under Remote response language.
  4. Enter the Bot token from @BotFather and the private Webhook secret token.
  5. Choose who may send messages. For restricted access, leave Accept messages from anyone off and enter one numeric Telegram user ID per line under Authorized provider senders. This is the message.from.id value in a Telegram Bot API update, not a username or chat ID. If you leave the list empty, SoAI accepts no senders.
  6. Under Chat execution, select a model and agent mode. Choose the workspace folder and display names, then select Edit parameters for account-specific model parameters.
  7. Choose any MCP tools the account may use. Turn on Require tool approval if SoAI should send an approval request to the Telegram conversation before running a tool that requires it.
  8. Select Save.

Remote response language controls built-in command, status, error, and interaction messages. To require a language for model answers, select Edit parameters and add that requirement to the System prompt.

SoAI checks the token before it stores the account, then installs its Telegram webhook. If Save reports that Telegram already sends this bot to a different webhook, turn on Replace an existing provider callback only when SoAI may replace it, then select Save again. A callback failure after storage leaves the account in Degraded state.

A Telegram message can contain a photo, document, audio file, voice message, or video, with or without supported message text or a caption. The server downloads the file, processes it with the same attachment pipeline used by Chat, and gives it to the model with the message. The file is also visible with that message in the matching Chat conversation. Telegram and server file limits still apply. See Attachments and file context for how models use different file types.

Telegram supports /help, /status, /cancel, and /new. Use the command by itself in a direct message. In a group, address it to the bot, for example /new@BotUsername. See Connect messaging apps to SoAI for what the commands do and how to answer agent questions or tool approval requests.

Keep Allow plaintext secret replies off unless you accept the risk of a secret appearing in Telegram history or notifications. See Secrets vault for how tools request and store credentials.

Use the conversation in SoAI Chat

You can open the Telegram conversation in Chat and send a message there. That message and its immediate reply stay in Chat; neither is copied to Telegram. Both remain in the conversation transcript, so the model can use them as context when it answers a later Telegram message.

Files attached to a message sent from Chat also stay there. They can affect later model replies, but the server does not forward them to Telegram.

Chat locks the model, agent mode, workspace, display names, parameters, and MCP tools saved with the messaging account. To change them, or to update the Telegram credentials or sender policy, select the Settings button at the right of the header, choose Settings, select Messaging, and use Edit for the account.

This account can have its own context length and therefore its own effective compaction limit. Under Chat execution, select Edit parameters, then set Context length (tokens) under Model settings. Clear it to use the selected model's default. A lower value gives this account a smaller context budget, so SoAI compacts older context sooner. If a smaller model gives worse answers as a conversation grows, lowering this value can keep its active prompt shorter without changing your other messaging accounts.

Automatic context compaction lets the conversation continue without a fixed message-count limit. SoAI keeps recent turns and may replace older details with a summary before sending the next prompt to the model. See Chat for more about context compaction.

Check the connection

Wait for the account row under Settings > Messaging to show Active and Provider connection healthy. Open the bot in Telegram, select Start if Telegram shows it, and send a direct message. The sender must match the account's sender policy. The setup works when SoAI replies in Telegram and the conversation appears in the SoAI Chat sidebar.

Direct messages provide the simplest test. For a group, add the bot to the group first. SoAI treats each supported message Telegram delivers from an allowed user as a prompt; Telegram's BotFather privacy setting controls which group messages Telegram delivers to the bot.

Everyone admitted in the same Telegram group shares one conversation and its model context. Each direct chat has its own conversation. Editing or deleting a Telegram message does not change the Chat transcript; send a new correction instead.

Fix common setup problems

If Telegram rejects the credentials, copy the current bot token from @BotFather and check the webhook secret. If SoAI reports a callback conflict, confirm that the previous service no longer needs the bot before allowing SoAI to replace its webhook. A missing or non-HTTPS Public Origin also prevents callback setup.

A saved account shows Degraded when provider activation fails. Correct the public address, credentials, or callback choice under Settings > Messaging > Edit, then save the account again.

Related documentation