🦀🐍 Telegram WebApp Auth Library

This library is a simple way to authenticate users in your web application using Telegram.

Example

For a complete example, check out the Example Bot repository.

Installation

Using pip

pip install teleapp-auth

Using Poetry

poetry add teleapp-auth

Using pipenv

pipenv install teleapp-auth

Using uv

uv pip install teleapp-auth

Usage

from fastapi import Request, FastAPI
from teleapp_auth import get_secret_key, parse_webapp_data, validate_webapp_data


app = FastAPI()
secret_key = get_secret_key("BOT_TOKEN")


@app.post("/check_data")
async def check_data(request: Request) -> bool:
    request_json = await request.json()
    auth_data = request_json.get("auth_data")  # Telegram auth data from the request
    webapp_data = parse_webapp_data(auth_data)  # Parse the auth data to the WebAppInitData object

    # Example of the parsed data:
    # WebAppInitData {
    #   query_id: "AAEt6-JYAAAAAC3r4lj2oADQ",
    #   user: WebAppUser {
    #       id: 1,
    #       is_bot: None,
    #       first_name: "Test",
    #       last_name: "",
    #       username: "test",
    #       language_code: "ru",
    #       is_premium: None,
    #       added_to_attachment_menu: None,
    #       allows_write_to_pm: true,
    #       photo_url: None
    #   },
    #  receiver: None,
    #  chat: None,
    #  chat_type: None,
    #  chat_instance: None,
    #  start_param: None,
    #  can_send_after: None,
    #  auth_date: 1726572911,
    #  hash: "f87a5a37a5b487700a35cb1e3d2e92afa67e4b67066c9f1fa2c34986c2350b6e
    # }
    

    return validate_webapp_data(webapp_data, secret_key)  # True if the data is valid, False otherwise

FAQ

1. What is the purpose of this library?

This library simplifies the process of authenticating users in your web application using Telegram WebApp authentication.

2. Can I get the user's profile photo with this library?

The photo_url field in the authentication data contains a URL to the user's profile photo. However, it is only available for Mini Apps launched from the attachment menu. Currently, integration with the attachment menu is only accessible to major advertisers on the Telegram Ad Platform. All bots can still test this feature in the test server environment by contacting Botfather on the test server.

3. Does this library automatically handle sending authentication data to my server?

No, you need to handle the process of sending the authentication data to your server. You can find an example of how to do this in the page.html file within the examples directory.

4. How do I validate the authentication data?

Use the validate_webapp_data function from the library to verify the authenticity of the data. This function compares the data with a secret key derived from your bot's token.

5. Can I use this library with any Python web framework?

Yes, the library is framework-agnostic, though examples are provided with FastAPI and Blacksheep. You can adapt it to other frameworks with minimal effort.