Skip to main content

Telegram client authentication

A Telegram client signs in automatically from the Mini App launch and gets a real Supabase Auth session, the same kind of session the website uses. Sharing a phone is a separate onboarding step that unlocks client account operations. It is not a condition for being signed in. See Authentication for how the API verifies the session.

:::caution Migration in progress The old Telegram exchange and bot webhook are gone; this release requires the client bot's webhook to point at the API's channel-authentication route. Deploy it together with the channel authentication cutover. :::

Account binding​

Channel authentication verifies the launch against the client bot, resolves one stable identity per Telegram user across both bots, and binds the client account before it returns the session. The binding either:

  • reuses the client account already bound to that Supabase subject;
  • creates an incomplete account with no phone, using the launch display name when one is present.

Retries reuse the same account. A Telegram ID or subject already bound to a different account is refused as a conflict and never merged. A phone number never selects, merges or moves an account.

Contact onboarding​

A new account is contact_required. The Mini App asks Telegram to share the contact and then polls the onboarding status with its existing session. It never opens another session to do so. The callback in the Mini App does not verify anything.

The client bot's update must show the sender sharing their own contact with a valid international phone. Channel authentication then applies the verified contact to the client account, which records the phone and its verification time. Duplicate or older facts change nothing. A repeated fact for the same phone keeps the original verification time. A delayed update leaves the account contact_required while the session stays usable.

What contact unlocks​

Until contact is verified, every existing client operation answers contact_required without ending the session:

  • profile;
  • appointment history and claims;
  • prior professionals;
  • notification preferences and inbox;
  • booking as the signed-in client.

Public browser booking keeps its own rules.

Bot write permission is reported separately from contact. A local permission callback can prompt a status refresh, but only a trusted bot update, delivered as a permission fact, records it. Notification preferences cannot grant it. See Client booking notifications.