Telegram Seamless Login

Implement seamless player authentication between your Telegram bot and your platform.

Player Flow

• Players open the casino’s bot on Telegram
• They click on the bot’s start button
• We register the player on your platform using the first API below
• Player receives the start message or other campaigns
• Player clicks on the play now call to action
• We redirect the player to your platform using a token (second api below), and the player is already logged in.

Player registration / Sign up

Description: 

A POST API call from Rapidpace to your Backend API to register the player. 

When: 

After the player clicks on the Telegram Bot’s “Start” (/start) button

URL: 

Your URL of choice.

Headers:

• content-type: application/json
• x-urm-hmac: [“HMAC VALUE”]

Body:

{
  "telegram_id": 542262331,
  "first_name": "Хади",
  "last_name": "Варпошти",
  "username": "hadivarp",
  "language_code": "en",
  "trace_id": "35b1baf8-a268-44cf-91cb-58112f29202f",
  "auth_date": 1687519459
}

‍

First, sort the key values alphabetically based on the keys.

 "auth_date": 1687519459,
  "first_name": "Хади",
  "language_code": "en",
  "last_name": "Варпошти",
  "telegram_id": 542262331,
  "trace_id": "35b1baf8-a268-44cf-91cb-58112f29202f",
  "username": "hadivarp",

‍

Then, create a string by appending the key values together:

auth_date1687519459first_nameХадиlanguage_codeenlast_nameВарпоштиtelegram_id542262331trace_id35b1baf8-a268-44cf-91cb-58112f29202fusernamehadivarp

Finally, produce the base64 encoded of SHA256 encryption of the above string, using your secret key.

The correct HMAC value for the above body using the test secret key ("URGv5f9J4KbAIkod02uLEXfUMEKhDE1s") is:

x-urm-hmac: RXfgLu5gZeWsq4FWcsKwhNVoKI5Jg+3iTm0i6GDSTpc=

HMAC Validation:

You need to encode the sorted string using your specific private secret key (provided by Rapidpace), and if the resulting hash is equal to the provided HMAC header, the request is. Below is a sample Ruby code snippet for this process:

hmac = event['headers']['x-urm-hmac']
  
secret_key = "URGv5f9J4KbAIkod02uLEXfUMEKhDE1s"
  
calculated_hmac = Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', secret_key, sorted_body))
  
if calculated_hmac == rapidpace_hmac
    # Request is valid
else
    # Request is invalid
end

* The secret_key in the code is for test purposes. Your production secret key will be provided to you.

If the request is valid, you can proceed with registering the player if it does not exist.

Player redirection / Sign-in

Description: 

A GET URL redirection to your website’s front-end URL with the required fields as a query string.

When: 

After the player clicks on a call to action, the bot’s mini app in Telegram opens.

URL: 

Your URL of choice (Front URL).

Query String: 

https://yourwebsite.com/redirect?trace_id%3D35b1baf8-a268-44cf-91cb-58112f29202f%26telegram_id%3D542262331%26first_name%3D%D0%A5%D0%B0%D0%B4%D0%B8%26last_name%3D%D0%92%D0%B0%D1%80%D0%BF%D0%BE%D1%88%D1%82%D0%B8%26language_code%3Den%26username%3Dhadivarp%26auth_date%3D1687519459%26x-urm-hmac%3DRXfgLu5gZeWsq4FWcsKwhNVoKI5Jg%2B3iTm0i6GDSTpc%3D

Same steps as the above:

First, sort the key values alphabetically based on the keys.

  "auth_date": 1687519459,
  "first_name": "Хади",
  "language_code": "en",
  "last_name": "Варпошти",
  "telegram_id": 542262331,
  "trace_id": "35b1baf8-a268-44cf-91cb-58112f29202f",
  "username": "hadivarp",

Then, create a string by appending the key values together:

auth_date1687519459first_nameХадиlanguage_codeenlast_nameВарпоштиtelegram_id542262331trace_id35b1baf8-a268-44cf-91cb-58112f29202fusernamehadivarp

Finally, use your secret key to produce the base64 encoded SHA256 encryption of the above string.

The correct HMAC value for the above body using the test secret key ("URGv5f9J4KbAIkod02uLEXfUMEKhDE1s") is:

x-urm-hmac: RXfgLu5gZeWsq4FWcsKwhNVoKI5Jg+3iTm0i6GDSTpc=

Notes:

• Idempotency must be implemented for both functionalities. The system may call the register API and redirect URLs with the same input data multiple times.

• Some parameters (e.g. last_name) may be sent as Null or an empty string. In this case, the key name with no value must be used in the HMAC calculation process.

• Only the telegram_id is required.