5.5 KiB
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 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:
- Open your Telegram group → Edit → Administrators → add your bot and enable at minimum "Manage Topics".
- Confirm the chat ID in
~/.openacp/config.jsonmatches the group. The ID of a group is negative (e.g.,-1001234567890). - 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:
- Promote the bot to administrator in the group settings.
- Enable Topics: Group Settings → Edit → Topics.
- 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:
- Confirm the bot is a member of the group.
- Check logs for error details.
- Run
openacp doctorto 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:
- Open the group in Telegram.
- Go to Group Settings → Administrators.
- Select your bot.
- Enable the Manage Topics toggle.
- 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:
- Add the bot to your group if you haven't already.
- Run
openacp doctor— it callsgetChatand reports the exact error from the Telegram API. - 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
maxConcurrentSessionsin 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:
- Check
security.maxConcurrentSessionsin~/.openacp/config.json— the default is low. Increase it if needed. - Check
security.allowedUserIds— if the array is non-empty, only listed user IDs can create sessions. Find your Telegram user ID with@userinfobotand 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:
- Ensure the bot is running — buttons expire after the bot restarts if not answered.
- If buttons appear but clicking does nothing, check logs for
Telegram bot errorentries that may indicate the bot token has been revoked. - 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
outputModeto"low"in your Telegram config to reduce the number of intermediate edits sent during streaming:
"telegram": {
"outputMode": "low"
}
The legacy key displayVerbosity is also accepted for backward compatibility.