nael_d / telegramify
Telegramify: Simplify Telegram verification code delivery, offering a more affordable, secure and reliable alternative to SMS.
Requires
- php: >=5.3
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
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 underTelegramify
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 therequest_id
from this response.Within the scope of a
request_id
, only one fee can be charged. CallingsendVerificationMessage
once with the returnedrequest_id
will be free of charge, while repeated calls will result in an error.Conversely, calls to
sendVerificationMessage
that don't include arequest_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
beforesendVerificationMessage
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 callsendVerificationMessage
with the returnedrequest_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 ofrequest_id
isnull
): The phone number to which you want to send a verification message, in the E.164 format. (Example: +123456789012345).request_id
(Optional in case ofphone_number
is passed): The unique identifier ID or array instance of a previous request fromcheckSendAbility
. 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 ofcode_length
isnull
): 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 ofcode
isnull
): 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 fromcheckSendAbility
. 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 therequest_id
from thesendVerificationMessage
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). Theverification_status
array contains necessary info about OTP validation with the user. Thestatus
may containcode_valid
orcode_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 fromcheckSendAbility
orsendVerificationMessage
.
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.