Troubleshooting

Telegram Session Expired

Symptom: Dashboard shows "Telegram disconnected" or syncs fail with a session error.

Cause: Telegram sessions can expire if you revoke them from Telegram's settings, change your password, or if Telegram detects unusual activity.

Fix: Go to Telegram in the dashboard and re-authenticate with your phone number and verification code.

Symptom: Digest shows "Complete" but the note isn't visible on the contact's HubSpot timeline.

Possible causes:

Contact not matched — Check the Contacts page to see if the Telegram user is matched to a HubSpot contact. Unmatched conversations don't create notes.
Wrong contact — Verify the match is correct. An auto name match might have linked to the wrong person.
HubSpot cache — Try hard-refreshing the HubSpot contact page (Ctrl+Shift+R).

Symptom: The "Sync Now" button was clicked but the status hasn't changed after several minutes.

Possible causes:

Large message volume — First syncs can take longer if you have many active conversations. Subsequent syncs are incremental and much faster.
Rate limiting — Telegram enforces strict rate limits. Conduits respects these and may pause during sync.
Worker not running — In self-hosted deployments, ensure the BullMQ worker process is running.

Fix: Wait 10 minutes. If still stuck, check the Digests page for error messages.

Symptom: Error message about flood wait or too many attempts.

Cause: Telegram rate-limits authentication attempts. This is a Telegram-side protection.

Fix: Wait the indicated time (usually 30 seconds to a few minutes) and try again. Do not repeatedly attempt — this extends the wait time.

Symptom: Some Telegram conversations don't appear in the dialog browser.

Possible causes:

Group conversations — By default, only DMs are shown. Enable "Include group conversations" in Settings to see groups.
Archived conversations — Archived Telegram chats may not appear in the dialog list.
Deleted accounts — Conversations with deleted Telegram accounts are skipped.

Symptom: A match shows 50% or lower confidence.

Cause: The match was made by fuzzy name matching, which is unreliable.

Fix: Go to Contacts and either confirm the match if it's correct, or ignore it and manually link the right HubSpot contact.

Symptom: Error during HubSpot connection or "OAuth failed" redirect.

Possible causes:

Insufficient permissions — Ensure you're a HubSpot admin or have permission to install integrations.
Portal mismatch — If you're logged into multiple HubSpot portals, ensure you're authorizing the correct one.
Browser extensions — Ad blockers or privacy extensions can interfere with OAuth redirects. Try in an incognito window.