Telegram

Telegram uses one Bot API token for triggers, messages, approvals, and lifecycle notifications.

Create and verify a bot

1. Open the verified @BotFather account.
2. Send /newbot, choose a name, and choose a username ending in bot.
3. Copy the returned token and store it.

woml secrets set TELEGRAM_BOT_TOKEN
woml telegram doctor

Test it

Run a workflow containing <telegram events="message" ... />, open the bot, press Start, and send a message. Use the normalized context.payload.conversationId as a notification chat ID. Group IDs may be negative; preserve the sign.

Only one long-polling owner should use a bot token. For all ordinary group messages, review BotFather privacy mode and re-add the bot after changing it.

Build a reply workflow

<telegram
  id="customerMessage"
  events="message"
  bot-token="{{secrets.TELEGRAM_BOT_TOKEN}}"
/>

Reply from a step:

const sent = await services.telegram.send({
  botToken: secrets.TELEGRAM_BOT_TOKEN,
  conversationId: context.payload.conversationId,
  text: `Received: ${context.payload.text}`,
  replyToMessageId: context.payload.messageId
}, { name: "reply-to-customer" });

return { messageId: sent.messageId };

The same conversation ID can be used in notification chats. Group IDs may begin with -100; store and pass the full signed value.

Test approvals

Add Telegram inside <approval><notify>. The bot sends inline Approve and Reject buttons. The first valid button press settles the shared durable approval even when other providers also delivered it.

Fix missing messages

Send /start in a direct chat before testing. In groups, add the bot and inspect privacy mode. Changing privacy mode may require removing and adding the bot again. Ensure no second process is polling the same token, because Telegram allows one effective long-polling owner.