> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exode.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Mini App integration

> How to create a user, get their token and sign them in automatically in a mini app via a bot

<Info>
  The Mini App opens inside Telegram WebApp and accepts the user's token via the <code>\_\_\_uat</code> GET
  parameter. With a valid token, the user is signed in automatically without login screens.
</Info>

#### To implement automatic sign-in at the API level:

<Steps>
  <Step title="Create a school user">
    1. Call [POST <code>/saas/v2/user/create</code>](/en/exode-api/school/user/create) (or
       [<code>user/upsert</code>](/en/exode-api/school/user/upsert) if the user may have been created earlier).
    2. Pass one of the logins (email, phone or domain); to link the account to Telegram, you can pass tgId. You can set the profile right away.
    3. Save <code>user.id</code> from the response — you will need it to issue the token.
  </Step>

  <Step title="Get a session token">
    1. Call [POST <code>/saas/v2/user/session/auth-token</code>](/en/exode-api/school/user/session/auth-token)
       with the body `{ "userId": 123 }`, where `123` is the <code>user.id</code> from the previous step.
    2. Take <code>payload.session.token</code> from the response — this is the value for <code>\_\_\_uat</code>.

    <Note>
      No token is issued for users with permissions in the admin panel (administrators, managers) — the method is intended for students.
    </Note>
  </Step>

  <Step title="Pass the link to the Telegram Mini App">
    1. Build the school URL with the <code>\_\_\_uat</code> parameter.
    2. Pass the link in the <code>startapp</code> payload when opening the WebApp from the bot, or send it to the user as a regular link.
    3. When the Mini App opens, the user is signed in automatically.

    ```bash theme={null}
    https://my-school.exode.biz?___uat=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.student-session-token
    ```

    <Tip>
      The most convenient way is to open the Mini App with a bot button: in the Bot API, pass the school URL with <code>\_\_\_uat</code> in the
      button's <code>web\_app.url</code> field (of an inline or reply keyboard). Telegram passes the <code>startapp</code> parameter of direct links
      (<code>[https://t.me/your\_school\_bot/app?startapp=](https://t.me/your_school_bot/app?startapp=)...</code>) to the Mini App as
      <code>start\_param</code>, not as the page address, so the token cannot be passed through it.
    </Tip>

    <Info>
      You can also pass the token in the fragment: <code>[https://my-school.exode.biz#\_\_\_uat=\&lt;token](https://my-school.exode.biz#___uat=\&lt;token)></code> — the fragment
      is not sent to the server and does not end up in web server logs. After sign-in, the platform removes the token from the address.
    </Info>

    <Check>
      If the token is valid and has not expired, the Mini App does not show the login screen — the user goes straight to the school interface.
    </Check>
  </Step>
</Steps>

## Common errors and how to avoid them

* Authorization error in the Mini App: make sure the token is passed in <code>\_\_\_uat</code> and has not expired.
* User not found when issuing the token: use the <code>user.id</code> from the user creation step.
* Telegram does not open the WebApp: check that the button is created as <code>web\_app</code> and the school URL starts with <code>https\://</code>.

<Warning>
  Do not share the token in public chats or groups. Use personal links.
</Warning>

***

*Updated: 2026-09-25 14:33 UTC*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.