fix(telegram): prevent message_thread_id in DMs causing 'thread not found' errors

[sroecker]

Summary

The Telegram adapter was passing message_thread_id even in direct messages (DMs), which don't support threading. This caused repeated "Message thread not found" errors when sending messages to users.

Changes

• Detect DMs and clear thread_id: Added logic to detect when the chat is a DM (chat_id > 0) and clear the thread_id before sending
• Expand error detection: Added more thread-related error strings to catch variations like "Message thread not found", "invalid message thread", etc.
• Improve logging: Enhanced the warning message to include the actual error for better debugging

Testing

• Tested in production DM conversations
• Confirmed no more "thread not found" errors after restart
• Messages now deliver successfully on first attempt

Fixes

Resolves repeated telegram.error.BadRequest: Message thread not found errors in direct message conversations.

[binhnt92]

Just a note — there's been quite a bit of prior work on this exact issue. #3390 (merged) already added a fallback that retries without message_thread_id when the send fails with "Message thread not found". There were also several earlier attempts (#3207, #3283, #3218) that were closed.

Your approach of proactively clearing the thread_id for DMs (chat_id > 0) is a nice defense-in-depth layer on top of the existing reactive fallback — might be worth mentioning that in the description so the reviewer can see how it complements what's already there.

[sroecker]

Just a note — there's been quite a bit of prior work on this exact issue. #3390 (merged) already added a fallback that retries without message_thread_id when the send fails with "Message thread not found". There were also several earlier attempts (#3207, #3283, #3218) that were closed.

Your approach of proactively clearing the thread_id for DMs (chat_id > 0) is a nice defense-in-depth layer on top of the existing reactive fallback — might be worth mentioning that in the description so the reviewer can see how it complements what's already there.

Thanks for checking. I think #3390 wasn't merged in v0.5.0 yet. I just asked my agent to fix any potential errors it found in the logs since Telegram chats got stuck a few times.

[dieutx]

Can confirm this bug is still there on v0.5.0. The fallback from #3390 only catches it for text messages — voice, audio, photo, document sends still break in DMs with "thread not found" since they have no retry logic. This PR actually fixes the root cause instead of patching the symptom.

[sroecker]

✅ Rebased to v0.6.0 and Enhanced

I've rebased this PR to the latest v0.6.0 (main) and significantly expanded the fix based on the feedback from @dieutx.

What was missing in the original PR

The original PR only fixed the send() method for text messages. As @dieutx correctly pointed out, the fallback from #3390 only catches errors for text messages — voice, audio, photo, document, video, and animation sends still break in DMs with "thread not found" since they have no retry logic.

What's now included

New helper method: _get_effective_thread_id(chat_id, thread_id)

• Proactively detects DMs (chat_id > 0) and clears thread_id before sending
• Reusable across all sending methods

All media methods now fixed:

• ✅ send() - text messages (refactored to use helper)
• ✅ send_voice() - voice messages and audio files
• ✅ send_image_file() - local image uploads
• ✅ send_document() - file attachments
• ✅ send_video() - video messages
• ✅ send_image() - URL-based photos
• ✅ send_animation() - GIFs and animations
• ✅ send_typing() - typing indicators

Root cause vs symptom

This PR now actually fixes the root cause (don't send thread_id in DMs) instead of patching the symptom (retrying after error). The proactive approach works for all message types, not just text.

Ready for review! 🚀

[sroecker]

🐛 Bugfix pushed: Added missing chat_id_int definition

During the refactoring to extract _get_effective_thread_id(), I accidentally removed the chat_id_int = int(chat_id) line from the send() method loop, which caused a NameError when sending messages.

Fix: Re-added chat_id_int = int(chat_id) inside the chunk loop.

The fix is now live and tested — messages are flowing correctly in DMs.

[teknium1]

Thanks for looking into this @sroecker — the 'thread not found' errors in DMs are a real pain point. However, the current codebase has DM Topics support (Bot API 9.4 createForumTopic for private chats, skill-bound topic routing, etc.) where thread_id in DMs is intentional. The blanket chat_id > 0 → clear thread_id rule would break that feature.

The existing retry logic in send() already handles the error case reactively (try with thread, fall back without), which is the right approach since it works for both topic-enabled and non-topic DMs. Appreciate the effort!