Connect FoneClaw to a Telegram Bot: Private Setup Guide
Create a dedicated Telegram bot with BotFather, pair it with FoneClaw in a private chat, verify one supported Android to-do, and fix token, network, webhook, pause, resume, or removal issues.
- Use the official BotFather to create a dedicated Telegram bot, keep the bot token private, and treat the token as bot authentication rather than a personal Telegram login code.
- Pair FoneClaw from a private chat with your own bot: save the token, open that bot, send hello within ten minutes, and wait for confirmation before chatting.
- A working Telegram chat only proves message delivery; verify a real supported Android result such as a saved undated to-do inside FoneClaw.
- Pause, resume, token update, webhook conflict, and connection removal have different effects, so diagnose the exact state before changing the bot.
Create a Dedicated Telegram Bot
To connect FoneClaw to Telegram, create a Telegram bot first. This is different from controlling the Telegram app by voice. A bot connection gives you a private Telegram chat entry for sending requests to FoneClaw; it does not give the bot access to all of your personal Telegram chats, groups, or channels. For voice operation inside Telegram itself, use the separate guide Telegram Voice Control: Messages, Channels, Bots.
Use Telegram's official BotFather tutorial as the reference, then open @BotFather in Telegram and send /newbot. BotFather will create the bot and give you a unique token. Keep that token private. It authenticates the bot, but it is not your Telegram account password and it is not a Telegram login code. Anyone with the token may be able to operate that bot, so do not post it in chat groups, screenshots, public documents, or support messages.
Use a dedicated bot for FoneClaw rather than reusing a bot that another service already uses. A fresh bot makes setup easier to diagnose and avoids conflicts with another poller or webhook. You do not need to write Telegram API code or host your own server for this FoneClaw setup path; you only need the bot token from BotFather and the FoneClaw app on Android. Current installation options are available on FoneClaw Download.
Pair Your Own Private Account
In FoneClaw, open the Telegram Connections screen. Paste the BotFather token into the BotFather token field and use Save bot token. After saving, open your own bot in Telegram, not BotFather, and send the literal message hello within ten minutes. Wait for the binding confirmation before you start sending real requests. If the connection window expires, tap Connect this chat on your phone to open a new indicated ten-minute window, then send hello to your own bot and wait for confirmation.
The first sender matters. FoneClaw binds the connection to the Telegram account that sends the first private message to that bot. Use your own Telegram account and the exact bot whose token you saved. If another person sends the first message, the connection may bind to that account instead. Private chats are the supported setup path here; do not use a group or channel as the first conversation.
This pairing step proves that Telegram messages can reach the connection. It does not grant Android permissions by itself, and it does not move approval decisions into Telegram. Supported Android actions still depend on the phone, the configured model, relevant permissions, and any applicable approval in FoneClaw. If you need a full first-task walkthrough after pairing, How to Use a Free AI Agent on Android with FoneClaw covers the broader Android setup path.
Check One Supported Android Result
After pairing, test one simple supported result. Use an undated to-do so the outcome is easy to inspect and does not require calendar details. A good first request is: Save a to-do: Review the camping checklist. This request contains no date, weekday, or relative day, so the saved item should remain unscheduled rather than becoming a calendar event.
Keep two checks separate: message delivery and saved result. The Telegram chat can show that your request was sent, but the useful success test is the visible saved item in FoneClaw. If a supported Android action needs a permission or an approval, handle that on the phone. Pairing a bot does not automatically approve every Android task.
After the request, inspect the saved to-do in FoneClaw. If your goal is to save ideas without making up a due date, Android AI To-Do Without a Due Date: Save It Safely explains that workflow in more detail. You can also review current supported areas on FoneClaw Features before expanding from one to-do into broader phone tasks.
Diagnose the Specific Connection Error
If setup fails, fix the specific state instead of changing everything at once. Most problems are caused by a token mismatch, the wrong bot, a missed first message, existing bot use, a network issue, or another service already using the bot.
| Problem | Likely cause | What to do |
|---|---|---|
| Token is rejected | The token was copied incorrectly or is not the token from BotFather for this bot. | Return to BotFather, copy the full token again, and save it in FoneClaw. |
| No confirmation after saving | You messaged BotFather, the wrong bot, or missed the pairing window. | Tap Connect this chat on your phone to open a new indicated ten-minute window, then send hello in a private chat with your own bot and wait for confirmation. |
| Bot already connected | The bot is already in use by an existing connection or account. | Use that existing connection if it is yours, or create a fresh dedicated bot. |
| Telegram cannot be reached | Network or Telegram connectivity is unavailable from the phone or service path. | Check connectivity and try again when Telegram is reachable. |
| Poller or webhook conflict | Another service is already receiving updates from the same bot. | Prefer a fresh dedicated bot. Remove a webhook only if you intend to stop delivery to its current endpoint. |
The webhook warning matters. Removing a webhook stops delivery to the current endpoint using that bot. If that endpoint belongs to another automation, website, or service you still need, create a new bot for FoneClaw instead of disrupting it.
Pause, Resume, or Remove a Connection
Use pause and resume when you want to control whether Telegram requests are accepted without rebuilding the whole setup. Pause connection stops the connection from accepting new Telegram requests. Resume connection turns it back on. If the connection is paused, sending new Telegram messages is not enough; resume the connection in FoneClaw first.
Token changes and removal have different consequences. Updating the bot token preserves the pairing and chat history. That is useful if you rotate the token for the same bot or replace a saved token while keeping the connection record. Removing a connection is stronger: it deletes the saved token, queued requests, and delivery records in FoneClaw. Local chat history is retained. Removing the local connection does not revoke the Telegram bot token itself.
There is no need to leave a bot connected for every task. Keep it enabled when you actually want Telegram as a private entry point, pause it when you want a quiet period, and remove it when you no longer want FoneClaw connected to that bot. FoneClaw still executes only supported Android actions with the configured model, relevant permissions, and applicable approval behavior. The Telegram bot is a request channel, not unrestricted automation.