craftsys / msg91-php
PHP Client for using Msg91's API to Send OTPs, Verify OTPs, Resend OTPs, Send SMS (Short Message) etc.
Installs: 62 438
Dependents: 1
Suggesters: 0
Security: 0
Stars: 6
Watchers: 2
Forks: 6
Open Issues: 1
Requires
- php: >=7.1|^8.0|^8.1|^8.2
- guzzlehttp/guzzle: ^6.5.5|^7.0.1
Requires (Dev)
- phpunit/phpunit: ^7.5|^8.4.0|^9.4|^10.0
This package is auto-updated.
Last update: 2024-10-17 06:22:54 UTC
README
Sponsor
This library requires a minimum PHP version of 7.1
This is a PHP Client for Msg91 APIs. Before using it, please make sure you have an account on Msg91 and have an Authkey (Msg91 Dashboard > API > Configure).
Table of Contents
Installation
The packages is available on Packagist and can be installed via Composer by executing following command in shell.
composer require craftsys/msg91-php
Usage
If you're using Composer, make sure the autoloader is included in your project's bootstrap file:
require_once "vendor/autoload.php";
Now the client can be initialised by passing a configured object to the constructor.
$config = [ 'key' => "123456789012345678901234", ]; $client = new Craftsys\Msg91\Client($config);
The package in distributed under Craftsys\Msg91
namespace which can used if your are working in a namespace environment.
<?php // in your use statement sections use Craftsys\Msg91\Client; // somewhere in this source file where you need the client $client = new Client($config); // send OTP using the otp service on client $client->otp()->to(919999999999)->send(); // verify an OTP (1234) $client->otp(1234)->to(919999999999)->verify(); // send SMS using the sms service on client $client->sms()->to(919999999999)->flow("<flow_id>")->send();
Continue reading to learn more about configuration and available method on opt
and sms
services with examples.
Create a Client
The client is responsible for interacting with Msg91 apis.
$client = new Craftsys\Msg91\Client($config);
Client can also be initialised without a configuration which can be set by calling setConfig($config)
method on the client instance.
$client = new Craftsys\Msg91\Client(); $client->setConfig($config);
You can also pass a custom GuzzleHttp\Client
as the second argument on the Client's constructor.
$client = new Craftsys\Msg91\Client($config, new GuzzleHttp\Client());
Configuration
The module is configurable to your specific needs where you need to set default options for APIs like the default OTP message format, retry method etc.
An example configuration might look something like this:
$config = [ 'key' => "123456789012345678901234", 'otp_message' => "G: ##OTP## is your verification code". ];
Following configuration options are available:
NOTE: Setting any if these values as null will override the default values to null too. And so, the default values from Msg91 APIs will be used. For example, setting the otp_message
to null
will let use "Your verification code is ##OTP##" which the default from APIS
OTP and SMS Services
After a client has been created, you can access otp
and sms
services to send OTPs and SMSs respectivily.
NOTE: Configuration must be set before using any other services on the client.
// send otp $client->otp()->to(919999999999)->send() // verify a given otp $client->otp(<otp_to_be_verified>)->to(919999999999)->verify() // resend otp via voice channel $client->otp()->to(919999999999)->viaVoice()->resend() // send sms $client->sms()->to(919999999999)->flow("<flow_id>")->send();
Next, follow along with examples to learn more
Examples
Managing OTPs
OTP services like sending, verifying, and resending etc, can be accessed via otp
method on the client instance e.g. $client->otp()
. All the parameters which are available for the Msg91 API, have a corresponding intuitive method name e.g. to set the digits in otp for the send OTP request, you call the digits
method on the service. You can create there via \Craftsys\Msg91\Options
class. See following examples to learn more.
Send OTP
Basic Usage
$otp = $client->otp(); // an OTP (optional) can be passed to service if you are generating otp on your end // $otp = $client->otp(4657); $otp->to(912343434312) // phone number with country code ->send(); // send the otp
Advanced Usage
Instead of relying on defaults from the Msg91 or the client, you can pass all the custom options that are accepted by Msg91 APIs using the options
helper on the service. This method accepts a close which will be called with underline \Craftsys\Msg91\OTP\Options
instance and gives your the full flexibility to add any options that is required.
$otp->to(91123123123) ->from("SENDER_ID") // sender id ->template("AFH") // template id for otps ->options(function (\Craftsys\Msg91\OTP\Options $options) { $options->digits(6) // set the number of digits in generated otp ->message("##OTP## is your verification code") // custom template ->expiresInMinutes(60); // set the expiry }) ->send() // finally send
NOTE: If you are generating the OTP at your side, and passing it to the service, along with a custom message, you MUST include the ##OTP##
or actual value of OTP inside the message. Failing to do so will result in error
// OK $client->otp(123242)->message('Your OTP is: 123242')->send(); // NOT OK! $client->otp(123123)->message("Use this for verification")->send(); // This will result in error with "Message doesn't contain otp"
Verify OTP
As the verification does not send any messages, you just need to provide the required fields to verify the OTP e.g. the sent OTP and Phone Number only.
$otp = $client->otp(12345); // OTP to be verified $otp->to(912343434312) // phone number with country code ->verify(); // Verify
Resend OTP
To resend an OTP, access to otp
service and call the resend
with to resend the OTP. Method of communication can be
changed by calling viaVoice
or viaText
before sending the OTP. The default values can be set into the configuration
$otp = $client->otp(); $otp->to(912343434312) // set the mobile with country code ->viaText() // or ->viaVoice() ->resend(); // resend otp
Sending SMS
To send SMS, access the SMSService
by calling ->sms()
method on the client instance
$sms = $client->sms(); $sms->to(912343434312) // set the mobile with country code ->flow('flow_id_here') // set the flow id ->message("You have 10 pending tasks for the end of the day") // message content ->send(); // send the message
To add any more options to the message, you can call the options
method before sending the message. The options
method accepts a call which will receive a \Craftsys\Msg91\SMS\Options
instance. Using it, you can modify any desired
option.
$client->sms() ->to(919999999999) ->flow('flow_id_here') // set the flow id ->options(function ($options) { $options->transactional() // set that it is a transactional message ->from('CMPNY') // set the sender ->unicode(); // handle unicode as the message contains unicode characters }) ->message("I ❤️ this package. Thanks.") ->send();
Message Variables
To send SMS, you create Flow where you can provide a template for your
SMS. This template may contain some variables which you use as placeholder
for per message data. You can use recipients
method to set the values for
these variables per recipient while sending SMS as follows.
Let's assume that you have create a Flow with following message template
Hi ##name##, Your reward credits will expire on ##date##.
Claim them to get exclusive benefits
We will to update the name
and date
variables per recipient.
$client->sms() ->flow('flow_id_here') // set the flow id ->recipients([ ['mobiles' => '919999999999', 'name' => 'Sudhir M', 'date' => '20 Jan, 2022'], ['mobiles' => '919898912312', 'name' => 'Craft Sys', 'date' => '25 Jan, 2022'] ]) ->options(function ($options) { $options->receiverKey('mobiles'); // set your receiver key }) ->send();
The mobiles
key in the recipients array comes from the receiver field's value
which we set when creating a new Flow. It defaults to mobiles
. If you have provided
a different receiver key, please update the recipients key accordingly.
If you want to put same value for a variable for all recipients, you can use
variable
method as follows
$client->sms() ->flow('flow_id_here') // set the flow id ->to([919898912312, 912343434312]) // you can pass an array of mobile numbers ->variable('overdue', 'Yes') // set the "overdue" variable's value to "Yes" ->variable('url', 'https://domain.com') // set the "url" variable's value to "https://domain.com" ->send(); // you can also combine this with existing variables if you want e.g. $client->sms() ->flow('flow_id_here') // set the flow id ->recipients([ ['mobiles' => '919999999999', 'name' => 'Sudhir M', 'date' => '20 Jan, 2022'], ['mobiles' => '919898912312', 'name' => 'Craft Sys', 'date' => '25 Jan, 2022'] ]) ->variable('overdue', 'Yes') // will set the "overdue" for all recipients ->send();
Note: You should call the variable
method only after you have set the recipients.
Receiver Key
When creating a Flow on MSG91, you can create a custom receiver key which default to ##mobiles##
. This default is
being used in this package as well. If you have configured your flow with a different receiver key, you can set it
via receiverKey
method as follows:
Assuming you have set the receiver field to ##contact##
,
$client->sms() ->to(919999999999) ->flow('flow_id_here') // set the flow id ->options(function ($options) { $options->receiverKey('contact'); // your receiver key }) ->send();
Handling Responses
All the services will return \Craftsys\Msg91\Support\Response
instance for all successfully responses and will throw
exceptions if
- \Craftsys\Msg91\Exceptions\ValidationException: request validation failed
- \Craftsys\Msg91\Exceptions\ResponseErrorException: there was an error in the response
try { $response = $client->otp()->to(919999999999)->send(); // response data // $response->getData(); // response message // $response->getMessage(); // response status code // $response->getStatusCode(); } catch (\Craftsys\Msg91\Exceptions\ValidationException $e) { // issue with the request e.g. token not provided } catch (\Craftsys\Msg91\Exceptions\ResponseErrorException $e) { // error thrown by msg91 apis or by http client } catch (\Exception $e) { // something else went wrong // please report if this happens :) }
Related
Acknowledgements
We are grateful to the authors of existing related projects for their ideas and collaboration: