Documentation

Setting up TelegramLogin


Before your service can use TelegramLogin's authentication system for user login, you have to register an app in the TelegramLogin Dashboard to retrieve your credentials, set a redirect URL and set a name and website (optional) that your users see on Telegram.

1. Create app

You need TelegramLogin credentials, including a client ID and client secret, to authenticate users via TelegramLogin's API. Therefore you have to register an app. To get your apps's Client ID and Cient Secret, register an app via the Dashboard:

Screenshot:
Create app screen

2. Set redirect URL

The redirect URL that you set, will be sent to the users Telegram app including the code and the state key, which you can later exchange for an access token (see Exchange code for Access Token).

E.g. if your redirect URL is https://telegramlogin.com/login, users will receive following link in Telegram with code and state as GET parameters:

Screenshot:
redirect url screen in Telegram

3. Obtain credentials

Your TelegramLogin credentials, including client ID and client secret, will be generated automatically and will be shown in the My apps overview.
Your client ID is your public identifier, but never share your client secret!

Screenshot:
Create app screen

Authenticate Users


Authenticating users involves obtaining an access token. Access tokens are a standardized feature and are designed for use in sharing users' identity. TelegramLogin's API flow allows the back-end server of a websevice to verify a user's identity using Telegram Messenger, either on Desktop or mobile devices.

1. Create anti forgery state token

This step is highly recommended, but can be skipped if you don't care about security.

You must protect the security of your users by preventing request forgery attacks. The first step is creating a unique session token that holds state between your app and the user's client. You later match this unique session token with the redirect URL response returned by Telegram to verify that the user is making the request and not a malicious attacker. These tokens are often referred to as cross-site request forgery (CSRF) tokens and will be referred as <your_csrf_token> in this document.

2. Send authentication request to TelegramLogin

The next step is to redirect the user to following url, containing your previously created unique state token:
https://telegramlogin.com/token/<your_client_id>?state=<your_csrf_token>
where <your_client_id> is your app's client ID and <your_csrf_token> is your state token.

Note: TelegramLogin creates a unique token on this endpoint to recognize the Telegram user to your app and redirects the user to https://telegram.me/TgLogin_Bot?start=<unique_token>. The https://telegram.me endpoint automatically tries to open the installed Telegram app. When the user clicks the Start button of the Bot (within the Telegram app), an access token for this Telegram user is automatically saved at TelegramLogin. The TgLogin_Bot replies with your specified redirect URL with a code parameter (and your state token), which can be later exchanged for an access token.

3. Confirm anti forgery state token

The user will receive your redirect URL via Telegram, containing the code and state as GET parameters. On the server, you must confirm that the state received from Telegram matches the session token you created in Step 1. This round-trip verification helps to ensure that the user, not a malicious script, is making the request.

4. Exchange code for access token

The response includes a code parameter, a one-time authorization code that your server can exchange for an access token. Your server can make this exchange by sending an HTTPS POST request.

The endpoint for the code exchange is https://telegramlogin.com/code and must contain these parameters:

code: the retrieved code parameter
client_id: your client ID
client_secret: your client secret

Example request:

POST /code
Host: telegramlogin.com
Content-Type: application/x-www-form-urlencoded

code=<retrieved_code>&
client_id=<your_client_id>&
client_secret=<your_client_secret>

A successful response to this request contains the TelegramLogin auth object as JSON:

{
    id: 42,
    email: "xxxxxxxxxx@telegramlogin.com",
    access_token: "ADD9PGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    active: 1,
    created_at: "2015-03-14 09:26:59",
    telegram_user: {
        telegram_id: 31415265,
        name: "David Pichsenmeister",
        username: "pichsenmeister",
        avatar: "path/to/avatar.jpg"
    }
}

Note: The avatar URL is relative and can be retrieved through following endpoint: https://telegramlogin.com/path/to/avatar.jpg

5. Obtain user information from access token

Once a valid access token is generated and the user haven't revoked access to your app, user information can be retrieved via the https://telegramlogin.com/user endpoint. Therefore the access token must be passed as access_token parameter. The request can be either GET or POST.

Example POST request:

POST /user
Host: telegramlogin.com
Content-Type: application/x-www-form-urlencoded

access_token=<access_token>

Example GET request:

GET /user?access_token=<access_token>
Host: telegramlogin.com

A successful response is the same as in Step 4:

Send message to user


A text message can be send to the user trough a POST request via the https://telegramlogin.com/user/send endpoint. Therefore the access token must be passed as access_token parameter and the text to send as text parameter.

Example POST request:

POST /user/send
Host: telegramlogin.com
Content-Type: application/x-www-form-urlencoded

access_token=<access_token>&
text=<some url encoded text>

The response is either a success message:

{
    ok: true
}
                    

or the detailed error message of Telegram:

{
    ok: false
    error_code: 403
    description: "[Error]: Forbidden: can't write to chat with deleted user"
}
                    

Create TelegramLogin button example


This is an example for Bootstrap + FontAwesome

HTML:
<a class="btn btn-logo" href="https://telegramlogin.com/token/<your_client_id>?state=<your_csrf_token>">
  <i class="fa fa-paper-plane-o"></i> Login with Telegram
</a>

CSS:
.btn-logo, .btn-logo:hover { background: #1e96c8; border-color: #1e96c8; color: #fff !important; }
.btn-logo:active, .btn-logo:focus { background: #057daf !important; border-color: #057daf !important; }

RESULT: