Troubleshooting

Webhook health fails

• Reconnect the bot token. Health checks Telegram’s webhook URL against /tg/{locationId} on the Optigram API host.
• Confirm the location still exists. Marketplace uninstall purges stored tokens and mappings; reconnect after a fresh install.
• Create the bot with BotFather; a revoked token fails getMe and will not stay connected.

Invite to Telegram is missing on the contact

• Confirm you are on the contact details page (the URL contains /contacts/detail/), not Conversations and not the contacts list.
• Open Optigram → Contact page and confirm Show Invite to Telegram on contact details is checked. Refresh the contact after you change it. Details: How to use.
• If the box is checked and the button is still missing, Custom JS may not be approved on this Marketplace app yet — use the Custom Page, paste the GHL contact id from the contact URL, generate, and share that link. See How to use.

Change how the Invite button looks

Agency Settings → Company → Custom CSS. Color and position variables are in How to use. The label is not editable.

SMS or email is disabled on Invite

SMS needs a phone on the contact and a sending number on the sub-account. Email needs an email address and a sending mailbox. Copy link still works if a bot is connected. A send failure is not a Telegram DM — Optigram never starts the chat.

Invite says already connected

That contact already tapped Start. Reply in the existing Conversations thread. Do not compose a new one.

A new GHL contact appeared instead of the existing lead

The opt-in QR was generated with the contact id left blank. That captures a new lead named from the Telegram profile. Optigram does not match by phone or name.

Delete the extra contact if it is a test. Generate a new link with the existing contact’s GHL id pasted in (copy it from the contact URL), and have them tap Start on that QR — not an old blank one. See How to use.

Sends fail with no_telegram_optin

That contact has no active Telegram mapping. The usual cause is starting from GHL: a new Conversations thread, composer send, or workflow to someone who never tapped Start. That is expected — Optigram will not cold-message them.

Generate an opt-in link (Invite on the contact, or contact-bound on the Custom Page if you already have the GHL contact), share it, and have them tap Start. Then reply in the thread that appears. Do not try to “just send” — Telegram will refuse a bot-initiated chat. See How to use.

Someone started the bot without an opt-in link

Telegram search, a shared bot username, or typing /start with no payload is always rejected. They are told they need an opt-in link. Optigram does not create a GHL contact, and the Custom Page has no capture or prompt setting. Share an Invite or Custom Page link instead. See How to use.

Media did not come through

MVP is text-first. Inbound photos are supported; voice, video, and documents may show as a placeholder. Outbound attachments from GHL are not sent as Telegram files yet. Full media parity is deferred.

Reading status in the dashboard

Open Optigram → message logs. Outbound rows show delivered vs failed (including no_telegram_optin). Usage shows recent counts and the 30/s and 1/s ceilings. Logs do not include message bodies.

Phantom phone on the contact

Expected for custom providers. Use the Telegram Handle custom field. See Install & connect.