Skip to content

Telegram relay

The Telegram relay forwards your iMessages to a Telegram bot and lets you reply from Telegram — the reply goes back as an iMessage or SMS from your Mac.

How it works

iMessage arrives → bridge detects it → Telegram bot sends it to your chat
You reply in Telegram → bot receives it → bridge sends via Messages.app → delivered as iMessage

Group chats are tracked by GUID — replies route back to the correct iMessage group, not to a random contact.

Prerequisites

  • A Telegram account
  • The chatwire-telegram plugin installed

Install the plugin

pipx inject chatwire chatwire-telegram
launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

Create a Telegram bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Follow the prompts to name your bot and get a username
  4. BotFather sends you a bot token — save it (looks like 7012345678:AAExxxxxx)

Keep the bot token private — anyone with it can send and receive through your bot.

Get your Telegram user ID

You need your numeric Telegram user ID to restrict who can use the bot (so only you can trigger relays).

  1. Search for @userinfobot in Telegram
  2. Start a chat with it — it replies with your user ID (a number like 123456789)

Configure the plugin

Open Settings → Plugins → Telegram in the web UI:

Field Value
Bot token The token from BotFather
Allowed user IDs Your Telegram user ID (comma-separated for multiple)
Relay groups Toggle on to relay group iMessages to Telegram

Click Save, then restart the bridge:

launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

Or in ~/.chatwire/config.json directly:

{
  "integrations": {
    "telegram": {
      "enabled": true,
      "bot_token": "7012345678:AAExxxxxx",
      "allowed_user_ids": [123456789]
    }
  }
}

Start the bot

Open Telegram, search for your bot by username, and send /start. The bot responds with a confirmation.

Receiving messages

When someone sends you an iMessage, the bot forwards it to your Telegram chat with: - The sender's name (from Contacts.app) or their phone number - The message text - Attachments (photos are sent as photos; other files as documents)

Group messages include the group name and sender name.

Sending replies

Reply to any forwarded message in Telegram to send an iMessage back:

  1. Long-press the forwarded message in Telegram
  2. Tap Reply
  3. Type your message and send

The bridge reads the reply context to route back to the correct conversation — including group chats.

Direct send (without replying to a specific message)

Send /send +15551234567 Hello from Telegram! to send a message to a specific handle without a prior forwarded context.

Relay commands

Command What it does
/start Activate the bot, confirm setup
/stop Pause relay (messages stop forwarding to Telegram)
/resume Resume relay after /stop
/status Show relay status and last activity
/send <handle> <text> Send to a specific handle
/whitelist add <handle> Add a contact to the relay whitelist
/whitelist list List whitelisted contacts

Security considerations

  • Allowed user IDs — the plugin only relays to and from Telegram accounts whose IDs are in the allowed list. If someone else finds your bot, they can message it but the bridge won't relay.
  • Bot token — treat the token like a password. Anyone with it can impersonate the bot.
  • Network — Telegram messages are transmitted to Telegram's servers (outside your Mac). Only metadata (sender, timestamp) and message content leave the Mac this way.

Troubleshooting

Messages aren't appearing in Telegram: - Check chatwire logs --service bridge -f for errors from the Telegram plugin - Verify the bot token and user ID are correct in Settings - Ensure the bridge restarted after plugin install: launchctl list | grep chatwire.bridge

Replies from Telegram aren't sending: - Verify you're replying to the forwarded message (not sending a new message) - Check the bridge log for AppleScript errors - Run chatwire doctor to confirm Automation → Messages is granted

Bot doesn't respond to /start: - The bridge must be running: curl localhost:8723/healthz - The plugin must be enabled in Settings → Plugins