Telegram service

⚠️ Simplified mode (2026-02-03): the current shipmyagent package disables approvals (full-permission execution). Mentions of “approval prompts” in older docs may be outdated.

Use Telegram to chat with ShipMyAgent (DM or group chat).

Want the internal flow? See: /en/docs/services/chat/telegram-message-flow

Setup

1) Create a Telegram bot

Open Telegram and find @BotFather
Send /newbot
Follow the prompts
Copy the HTTP API Token

2) Configure your project

Add the token to your project .env (same directory as ship.json):

TELEGRAM_BOT_TOKEN=123456:abc...

Enable Telegram in ship.json:

{
  "services": {
    "chat": {
      "channels": {
        "telegram": {
          "enabled": true,
          "botToken": "${TELEGRAM_BOT_TOKEN}"
        }
      }
    }
  }
}

ShipMyAgent uses a tool-strict chat mode: the agent should use the chat_send tool to decide when/how to send replies (multiple/staged messages are allowed).

Optional: restrict group access

By default, groupAccess is anyone, so all group members can talk to the bot.

If you want a stricter policy (only the initiator or group admins), set:

{
  "services": {
    "chat": {
      "channels": {
        "telegram": {
          "enabled": true,
          "botToken": "${TELEGRAM_BOT_TOKEN}",
          "groupAccess": "initiator_or_admin"
        }
      }
    }
  }
}

3) Start ShipMyAgent

sma agent on

In logs you should see:

Starting Telegram Bot...
Bot username: @...
Telegram Bot started

How to use

Direct message (DM)

Send /start (or any message) to your bot.

Send files (PDF / images / audio / video)

You can send a file directly to the bot (document/photo/voice/audio/video).

If you add text while sending the file, Telegram treats it as a caption — ShipMyAgent will read that caption as your instruction.
ShipMyAgent saves the file under .ship/.cache/telegram/ and passes it to the agent as an @attach ... line.

Example: send a PDF with caption: Summarize this PDF and list action items.

Local STT model management

If you want to manage local voice-to-text models, use the dedicated voice extension command group:

# enable and install model
sma voice on SenseVoiceSmall

# inspect current voice config
sma voice status

When extensions.voice.enabled=true, incoming Telegram voice/audio attachments are transcribed in best-effort mode and appended into the user instruction.

Group / supergroup

Add the bot to the group
Talk to it by mentioning: @your_bot ...
After you mention (or reply to the bot), you can send follow-up messages for a short time without mentioning again.

Notes:

If your group uses Topics, replies are sent back to the same topic.
In groups, ShipMyAgent may restrict who can talk to the bot (e.g. initiator/admin), depending on the runtime’s policy.
For file messages in groups, the mention (if needed) must be in the caption, or send the file as a reply to the bot.
While the agent is running, Telegram shows a periodic typing indicator (sendChatAction) until the result is sent.

Reply-to and Reaction Logic (Important)

This section explains:

when outbound sends use reply_to_message
when to use chat react instead of a full text reply

1) How `reply_to_message` is decided

When the agent runs sma chat send, default behavior is a normal non-reply send. Runtime only attempts reply_to_message_id when reply mode is explicitly enabled (for example sma chat send --reply).

messageId source priority:

explicit input argument (for example --message-id <id>)
latest inbound message metadata stored for the same chatKey (chat meta)

Behavior:

valid numeric messageId exists: send with reply_to_message_id
no valid messageId: still sends as a normal message (without reply link)
same rule applies to text and attachments

2) How `chat react` works

Use chat react for lightweight acknowledgement/attitude, e.g.:

"got it"
"agree"
quick encouragement

Examples:

# default 👍
sma chat react

# custom emoji
sma chat react --emoji '🔥'

# explicit target message
sma chat react --emoji '✅' --message-id 12345 --chat-key telegram-chat--100xxxx

Behavior:

default emoji: 👍
--big enables Telegram is_big
if --message-id is missing, runtime tries latest inbound messageId from the same chatKey
if no valid messageId is available, chat react fails (reactions must target an existing message)

3) Recommended usage

Use sma chat send for actual user-facing answers.
Use sma chat react for short acknowledgement/attitude only.
Use sma chat send --reply only when you explicitly need thread-style targeting in busy chats.
For cross-chat actions, always pass --chat-key.
In a brand-new chat with no inbound message yet, ask the user to send one message first before reply/react targeting.

Troubleshooting

No response at all: confirm the process is running and check .ship/logs/<YYYY-MM-DD>.jsonl (search for TELEGRAM, telegram, or errors).
Bot doesn’t receive group messages: in BotFather run /setprivacy and set it to Disable, then make sure you’re mentioning the bot in the group.
Polling doesn’t work: if you previously set a webhook, polling (getUpdates) will conflict. ShipMyAgent clears webhook on startup; check logs for webhook-related errors.
Bot can’t speak in the group: check group permissions (the bot may be muted / not allowed to send messages).
Agent says “I’ll execute” but doesn’t run tools: explicitly ask with execution intent words (for example run, execute, use skill, lookup). Runtime will force a tool call on these turns; if it still fails, verify your model/provider actually supports tool calling.