# Telegram Issues Run `openacp doctor` first — it validates your bot token, chat ID, group type, and admin status automatically. If you haven't finished initial setup, see the [Telegram Setup guide](../platform-setup/telegram.md) first. --- ### Bot doesn't respond to messages **Symptoms:** You send a message in Telegram but the bot stays silent. **Cause:** The most common cause is that the bot is not an administrator in the group, or the `chatId` in your config does not match the actual group. **Solution:** 1. Open your Telegram group → **Edit → Administrators** → add your bot and enable at minimum "Manage Topics". 2. Confirm the chat ID in `~/.openacp/config.json` matches the group. The ID of a group is negative (e.g., `-1001234567890`). 3. Restart OpenACP after making changes. --- ### "Not enough rights" error in logs **Symptoms:** OpenACP logs show `Not enough rights` or `TOPIC_CLOSED` errors when trying to send messages. **Cause:** The bot lacks administrator permissions in the group, or Topics are not enabled. **Solution:** 1. Promote the bot to administrator in the group settings. 2. Enable Topics: **Group Settings → Edit → Topics**. 3. In the bot's admin settings, ensure "Manage Topics" is enabled. --- ### Topics are not created on startup **Symptoms:** OpenACP starts but no "Notifications" or "Assistant" topics appear. **Cause:** Either Topics are not enabled on the group, or the bot lacks the "Manage Topics" admin permission. **New behavior (automatic):** OpenACP detects this at startup and sends a message to the group's **General** topic listing exactly what needs to be fixed. It then retries every 30 seconds automatically. Once the issues are resolved, topics are created and a confirmation message is sent. **If you don't see the setup message:** 1. Confirm the bot is a member of the group. 2. Check logs for error details. 3. Run `openacp doctor` to diagnose. --- ### Bot cannot manage topics **Symptoms:** Topics are enabled, but the bot still cannot create session topics. Logs may show `Not enough rights to manage forum topics`. **Cause:** The bot is an admin but the "Manage Topics" permission is not enabled in its admin role. **Solution:** 1. Open the group in Telegram. 2. Go to **Group Settings → Administrators**. 3. Select your bot. 4. Enable the **Manage Topics** toggle. 5. Save. OpenACP will detect this within 30 seconds and complete setup automatically. --- ### "Chat not found" error **Symptoms:** Logs show `Chat not found` or `Bad Request: chat not found` immediately on startup. **Cause:** The `chatId` in config is wrong, or the bot has never been added to the group (Telegram only returns chat info for groups the bot is a member of). **Solution:** 1. Add the bot to your group if you haven't already. 2. Run `openacp doctor` — it calls `getChat` and reports the exact error from the Telegram API. 3. If the ID looks correct, check that it is a negative integer for groups. --- ### Rate limiting — messages are delayed or dropped **Symptoms:** Responses appear sporadically, logs show `Rate limited by Telegram, retrying` with a `retryAfter` value. **Cause:** Telegram enforces rate limits per bot per chat (roughly 20 messages per minute per group). OpenACP automatically retries up to 3 times with the delay Telegram specifies, but heavy usage can still cause visible delays. **Solution:** - This is normal behaviour under load. OpenACP's send queue handles it automatically. - Avoid triggering many sessions simultaneously. - If the problem is persistent, consider lowering `maxConcurrentSessions` in your config to reduce outbound message volume. --- ### Session doesn't start after sending a message **Symptoms:** You send a message but no new topic appears and the agent doesn't respond. **Cause:** Either the concurrent session limit has been reached, or your user ID is not in `allowedUserIds`. **Solution:** 1. Check `security.maxConcurrentSessions` in `~/.openacp/config.json` — the default is low. Increase it if needed. 2. Check `security.allowedUserIds` — if the array is non-empty, only listed user IDs can create sessions. Find your Telegram user ID with `@userinfobot` and add it. --- ### Permission buttons are missing or unresponsive **Symptoms:** The agent asks for permission but no buttons appear, or clicking buttons does nothing. **Cause:** Callback queries (button clicks) are only delivered if `callback_query` is listed in `allowed_updates`. OpenACP sets this automatically on every polling cycle, but the bot must be running when buttons are clicked. **Solution:** 1. Ensure the bot is running — buttons expire after the bot restarts if not answered. 2. If buttons appear but clicking does nothing, check logs for `Telegram bot error` entries that may indicate the bot token has been revoked. 3. Re-run setup (`openacp onboard`) to regenerate configuration if the token is suspect. --- ### Streaming responses flicker or show duplicate edits **Symptoms:** Agent responses appear to flash or update repeatedly instead of streaming smoothly. **Cause:** Telegram rate-limits `editMessageText` calls. OpenACP batches updates with a send queue (default 3-second window), but under heavy load edits can still appear jumpy. **Solution:** - This is a Telegram API constraint, not an OpenACP bug. - Lower `outputMode` to `"low"` in your Telegram config to reduce the number of intermediate edits sent during streaming: ```json "telegram": { "outputMode": "low" } ``` The legacy key `displayVerbosity` is also accepted for backward compatibility.