README

Telegramify is a PHP library that serves as a gateway for integrating Telegram's messaging capabilities into your application.

With Telegramify, you can effortlessly send verification messages, check send ability, verify codes, and revoke messages directly through Telegram's Gateway API.

This library is designed for developers looking for a structured and efficient way to interact with Telegram for verification processes.

Features

• Send verification code and OTP messages to specified phone numbers.
• Check the ability to send verification messages.
• Verify the status of sent verification codes.
• Revoke verification messages when necessary.

Table of Contents

• Installation
• Getting Started
• API Methods
  • checkSendAbility
  • sendVerificationMessage
  • checkVerificationStatus
  • revokeVerificationMessage
• License

Installation

Telegramify is available to be installed through Composer:

composer require nael_d/telegramify

You are also able to download Telegramify manually. Download Telegramify and require src/Telegramify.php.

For a better release checking, we may suggest to review Releases page to pick up and review developing timeline, as it provides a clear listing of versions along with detailed descriptions of each release.

Getting Started

Once installed, the class Telegramify is ready for you.

Telegramify class is available under Telegramify namespace.

The first thing that you need before you go on, you have to obtain a new API token key from Telegram Gateway. Login with your phone number as following:

Then, Go to API then copy your token key:

Once copied, initialize Telegramify with your token to get started:

\Telegramify\Telegramify::setAccessToken("YourAPITokenKey");

It's a good practice to store it in an .env file for a better flexible managing:

\Telegramify\Telegramify::setAccessToken(env('TELEGRAM_API_TOKEN'));

API Methods

As outlined in the Telegram Gateway documentation, Telegramify API interface includes four methods:

All methods are always free of charge when used to send codes to your own phone number.

• checkSendAbility:

  Use this method to optionally check the ability to send a verification message to the specified phone number.

  If the ability to send is confirmed, a fee will apply according to the pricing plan.

  After checking, you can send a verification message using the sendVerificationMessage method, providing the request_id from this response.

  Within the scope of a request_id, only one fee can be charged. Calling sendVerificationMessage once with the returned request_id will be free of charge, while repeated calls will result in an error.

  Conversely, calls to sendVerificationMessage that don't include a request_id will spawn new requests and incur the respective fees accordingly.

  It has this parameter:

  • phone_number (Required): The phone number to which you want to send a verification message, in the E.164 format. (Example: +123456789012345).

  💡 Best practice: It's best to use checkSendAbility before sendVerificationMessage when a user requests their OTP verification code. This method checks if the user's number is registered on Telegram, improving the UI/UX by notifying them if it's not. If the number is registered, you can then call sendVerificationMessage with the returned request_id to send the OTP code.

  \Telegramify\Telegramify::setAccessToken("YourAPITokenKey");
    
  $check = \Telegramify\Telegramify::checkSendAbility("+123456789012345");
    
  var_dump($check);
  // $check['ok'] => true OR false
    
  // if true:
  // $check['result']['request_id'] => to be used later in `sendVerificationMessage()`
    
  /** Full dumping `$check`:
    array(2) {
      ["ok"]=> bool(true)
      ["result"]=> array(4) {
        ["request_id"]=> string "209903323001258"
        ["phone_number"]=> string "123456789012345"
        ["request_cost"]=> int(0)
        ["remaining_balance"]=> int(0)
      }
    }
   */
  

• sendVerificationMessage:

  Use this method to send a verification message. Charges will apply according to the pricing plan for each successful message delivery.

  It has these parameters as ordered:

  • phone_number (Required in case of request_id is null): The phone number to which you want to send a verification message, in the E.164 format. (Example: +123456789012345).
  • request_id (Optional in case of phone_number is passed): The unique identifier ID or array instance of a previous request from checkSendAbility. If provided, this request now will be free of charge.
  • sender_username (Optional): The Username of the Telegram channel from which the code will be sent. The specified channel, if any, must be verified and owned by the same account who owns the Gateway API token.
  • code (Required in case of code_length is null): The verification code. Use this parameter if you want to set the verification code yourself. Only fully numeric strings between 4 and 8 characters in length are supported. If this parameter is set, code_length is ignored.
  • code_length (Required in case of code is null): The length of the verification code if Telegram needs to generate it for you. Supported values are from 4 to 8.
  • callback_url (Optional): An HTTPS URL where you want to receive delivery reports related to the sent message, 0-256 bytes.
  • payload (Optional): Custom payload, 0-128 bytes. This will not be displayed to the user, use it for your internal processes.
  • ttl (Optional): Time-to-live (in seconds) before the message expires and is deleted. The message will not be deleted if it has already been read. If not specified, the message will not be deleted. Supported values are from 60 to 86400.

  💡 If you're on PHP >= 8.0.0, you may use named parameters specifically instead of passing null to escape parameters.

  use \Telegramify\Telegramify;
  Telegramify::setAccessToken("YourAPITokenKey");
  $check = Telegramify::checkSendAbility("+123456789012345");
  
  //////////////// Examples: ////////////////
  
  // 1. Check for the receiver's number validity then send a SPECIFIC OTP code:
  if ($check['ok']) {
    // PHP < 8.0.0
    Telegramify::sendVerificationMessage("+123456789012345", $check['result']['request_id'], null, "85647213");
  
    // PHP >= 8.0.0
    Telegramify::sendVerificationMessage(
      phone_number: "+123456789012345",
      request_id: $check['result']['request_id'],
      code: "85647213"
    );
  }
  else {
    // Provided number is not on Telegram
    echo "The phone number is not on Telegram. Use another method to validate your account.";
  }
  
  //** From now on, all next examples always assume that the PHP version is >= 8.0.0 and `$check['ok'] === true` **//
  
  // 2. Send an auto-generated OTP code after checking; limiting the OTP code length to 8 digits:
  Telegramify::sendVerificationMessage(
    phone_number: "+123456789012345",
    request_id: $check['result']['request_id'],
    code_length: 8
  );
  
  // 3. Send an OTP code after checking with a limited expiration period IF the user hasn't read the message.
  //    If the user opened the message, it won't be deleted ever.
  Telegramify::sendVerificationMessage(
    phone_number: "+123456789012345",
    request_id: $check['result']['request_id'],
    code_length: 8,
    ttl: 60, /* 60 seconds for auto-deletion if not opened */
  );
  

  💡 For in-depth info, visit Telegram Gateway Documentation.

• checkVerificationStatus:

  Use this method to check the status of a verification message that was sent previously.

  If the code was manually set by you, you can also verify the correctness of the code entered by the user using this method.

  It has these parameters as ordered:

  • request_id (Required): The unique identifier ID or array instance of a previous request from checkSendAbility. If provided, this request now will be free of charge.
  • code (Required): The verification code provided by the user.

  💡 If you ever want to skip using checkSendAbility, you may still get the request_id from the sendVerificationMessage instance.

  💡 Even if you set the code yourself, it is recommended to call this method after the user has successfully entered the code, passing the correct code in the code parameter, so that we can track the conversion rate of your verifications.

  use \Telegramify\Telegramify;
  Telegramify::setAccessToken("YourAPITokenKey");
  $check = Telegramify::checkSendAbility("+123456789012345");
  $input = $_POST['otp-code']; /* Sanitize `$_POST['otp-code']` before use */
  
  // Assuming $check['ok'] === true
  // Sending the $code OTP to the user's phone number through Telegram:
  $otp = Telegramify::sendVerificationMessage(
    phone_number: "+123456789012345",
    request_id: $check['result']['request_id'], /* <= If no `checkSendAbility`, skip this parameter */
    code_length: 8
  );
  
  // Matching $input with $otp:
  // You may get the `request_id` from $otp if you didn't perform a `checkSendAbility` request.
  Telegramify::checkVerificationStatus($otp['result']['request_id'], $input);
  
  // Even if you've set the OTP code manually, it's a better practice to do the verification through that method:
  $generated_code = "1475369";
  $input = $_POST['otp-code']; /* Sanitize `$_POST['otp-code']` before use */
  $otp = Telegramify::sendVerificationMessage(
    phone_number: "+123456789012345",
    code: $generated_code
  );
  
  // Best practice (Recommended):
  $match = Telegramify::checkVerificationStatus($otp, $input);
  
  // Legacy way (Not recommended):
  if ($generated_code == $input) {
    // Matched
  }
  else {
    // Not matched
  }
  
  /*
    // Dumping $match:
    array(2) {
      ["ok"]=> bool(true)
      ["result"]=> array(5) {
        ["request_id"]=> string(15) "128312894559459"
        ["phone_number"]=> string "123456789012345"
        ["request_cost"]=> int(0)
        ["delivery_status"]=> array(2) {
          ["status"]=> string "sent" **OR** "read"
          ["updated_at"]=> int(1729955234)
        }
        ["verification_status"]=> array(3) {
          ["status"]=> string "code_invalid" **OR** "code_valid"
          ["updated_at"]=> int(1729955285)
          ["code_entered"]=> string "00000000" <- ($input)
        }
      }
    }
  */
  

  The ok key represents the request's status itself (performed and charged from your balance). The verification_status array contains necessary info about OTP validation with the user. The status may contain code_valid or code_invalid.

  💡 Useful hint: The delivery_status key indicates if and when the user has opened the message.

• revokeVerificationMessage:

  Use this method to revoke a verification message that was sent previously. It returns true if the revocation REQUEST was received. However, this doesn't guarantee that the message will be deleted. For example, it won't be removed if the recipient has already read it.

  It has this parameter:

  • request_id (Required): The unique identifier ID or array instance of a previous request from checkSendAbility or sendVerificationMessage.

  use \Telegramify\Telegramify;
  Telegramify::setAccessToken("YourAPITokenKey");
  $otp = Telegramify::sendVerificationMessage(
    phone_number: "+123456789012345",
    code: '1475369'
  );
  
  // Revoking the $code OTP message from the user's phone number through Telegram:
  $revoke = Telegramify::revokeVerificationMessage($otp['result']['request_id']);
  
  /*
    // Dumping $revoke:
    array(2) {
      ["ok"]=> bool(true)
      ["result"]=> bool(true)
    }
  */
  

• getAccessToken:

  Returns the stored API Token.

  use \Telegramify\Telegramify;
  Telegramify::setAccessToken("YourAPITokenKey");
  
  echo Telegramify::getAccessToken();
  // outputs: "YourAPITokenKey"
  

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0). You are free to use, modify, and distribute this library under the terms of the MPL-2.0. See the LICENSE file for details.