Use Local Waifu from Telegram

Telegram lets you talk to the same active companion from your phone. The desktop app and Telegram share the active character, conversations, model settings, and memory. Telegram has its own reply-mode setting.

Security warning: Treat the Telegram bot token like a password. Do not paste it into screenshots, public bug reports, or chat messages. The first Telegram chat that messages the bot becomes the pinned owner. Messages and commands from other chat IDs are rejected.

Connect a Telegram bot

Goal

Create a private Telegram bot, verify its token, start the Local Waifu bridge, and pair your Telegram account.

Before you start

• Local Waifu must be open on your computer and connected to the internet.
• Install and configure the chat model you want to use.
• For Telegram voice messages, configure speech recognition under Settings → Models → Voice Model.
• For spoken replies, install and configure a voice model.
• You need a Telegram account.

Steps

1. In Telegram, open the verified bot named @BotFather.
2. Send /newbot and follow BotFather’s instructions to choose a name and username.
3. Copy the token issued by BotFather. A token resembles 123456:ABC-DEF....
4. In Local Waifu, open Settings → Telegram.
5. Paste the token into Bot token.
6. Select Test. This verifies the token with Telegram without saving it or starting the bot.
7. Confirm that Local Waifu reports Token works: bot is @….
8. Select Start. The status should change to Running.
9. Open your new bot in Telegram and send /start or a normal message from the account you want to pair.
10. Return to Settings → Telegram and confirm that Pinned chat id is displayed instead of No chat pinned yet.

Expected result

The bot is Running, your Telegram chat is pinned as its owner, and messages sent to the bot reach the same Local Waifu companion used by the desktop app.

If something goes wrong

• If Test says Telegram rejected the token, copy a fresh token from BotFather and make sure no characters or spaces are missing.
• If Test succeeds but the bot does not answer, select Start; Test does not save the token or start polling.
• If the wrong Telegram account was paired, use Forget token + pin, start the bot again, and send the first message from the correct account.
• If the bot is running but chat fails, check Settings → Hardware → Runtime status, the active model, internet access, and Offline Mode.

Choose how Telegram replies

Goal

Choose whether Telegram receives text, voice, or both without changing desktop voice calls.

Before you start

The Telegram bot must show Running. A ready voice model is required for reliable voice replies.

Steps

1. Open Settings → Telegram.
2. Under Telegram settings, find How she replies here.
3. Choose one mode:
   • Voice + text: sends both forms; this is the default.
   • Text only: sends text without a voice note.
   • Voice only: sends a voice note instead of text.
4. Send a short test message to the bot.

Expected result

The bot replies in the selected Telegram-only format. Desktop voice-call behavior is unchanged.

If something goes wrong

• In Voice only, Local Waifu deliberately falls back to text if the voice model is unavailable, so the bot does not remain silent.
• Voice notes sent to the bot are always transcribed. Configure the transcription provider in Settings → Models → Voice Model.
• If speech is in the wrong language or sounds poor, check the configured voice language and installed voice model.

Use photos, voice messages, and bot commands

Goal

Use the bot’s supported media and discover the commands available in your installed build.

Before you start

For image understanding, a vision-capable route must be ready. For incoming voice notes, speech recognition must be ready.

Steps

1. Send normal text, a photo containing text, or a Telegram voice message to the bot.
2. In Local Waifu, open Settings → Telegram → Available commands.
3. Use Telegram’s / menu to choose a command. The list is generated by the app, so it is the authoritative list for your build.
4. Common commands include /help, /ping, /status, /response, /think, /model, /voices, /lang, /imgmodel, /mood, /newchat, /reset, and /image <prompt>.
5. For dynamic lists such as models or voices, select the numbered command presented by the bot.

Expected result

Text is handled as chat, text in photos can be read, voice messages are transcribed, and commands open the corresponding choices or actions.

If something goes wrong

• If a photo is ignored, verify that a vision-capable model or provider is available.
• If a voice note cannot be understood, check speech recognition under Settings → Models → Voice Model.
• Model changes made through Telegram also affect the desktop app because both interfaces share the active model.
• /reset asks for explicit confirmation. Read the bot’s prompt before confirming.
• An unknown slash command may be treated as normal conversation text.

Stop the bot or remove its credentials

Goal

Pause Telegram access or completely remove the saved token and owner pairing.

Before you start

Understand the difference:

• Stop pauses the bridge but keeps the token and pinned owner.
• Forget token + pin stops the bridge and removes both the saved token and pairing.

Steps

1. Open Settings → Telegram.
2. To pause the bot, select Stop.
3. To remove access completely, select Forget token + pin.
4. Select Yes, forget to confirm.

Expected result

After Stop, the status is Stopped and the same configuration can be started again. After Forget token + pin, the token and owner pairing are removed, allowing a new token or owner to be configured.

If something goes wrong

Forget token + pin remains available even while the bot is stopped. Use it if a stale token or old owner pairing prevents a new setup.

---