API

2. Select the SMS option from the dashboard 

3. Under "SMS", click "Support" in the sidebar & Select the API documentation option on the dropdown.

4. API documentation will get opened.

5. You can fill in the parameters, such as template ID (MSG91 template ID), mobile number (including country code), and variables, to get the final API. In the header option, enter the Authkey, and then press "Try" to send the SMS. On the right side of the panel, by clicking on the "more" option in Sample Codes, you can get the API codes in various languages. 

NOTE:

For SMS API integration, variable values keep on changing, you may have 1, 2, 3 variables: or so. Pass the variables in the API depending on the variables you have in your flow and write the variable in the exact format as you did while creating the flow (this is case-sensitive as well). 

1. The mobile variable will always be dynamic, and you have to insert it into the API, which is the mobile number of the user to whom you want to send SMS. 

2. To shorten the URL in your content, pass the value as 1. 

3. The message variable can be static or dynamic, as per your implementation.

4. The authentication key should always be static.

5. In case you want to send the promotional message using the numeric sender ID then please add the parameter route=1 in the payload.

NOTE: If sent without a country code, submission and deduction depend on the detected country based on the starting number: For, 91xxxxxxxxxx, etc

Frequently Asked Questions

Can I send SMS to international numbers using MSG91's API?

You may send SMS to international numbers using MSG91's API. Just make sure to use the full international phone number format, including the country code. Additionally, set the country parameter to 0 in your API request to indicate it's an international message. Let me know if you need more information!

Is there any way to schedule SMS for a specific time?

SMS can be scheduled for a specific time. You can set a future date and time for sending the message by using the send_at parameter in the API request. This allows you to specify when the message should be sent.

Is there any way to automate SMS sending based on triggers or events?

SMS sending can be automated based on triggers or events using MSG91's API. You can integrate the API with your system to send SMS automatically when certain conditions are met, such as when a user registers, places an order, or performs any action that your system tracks.

Can I customize the sender ID when sending SMS using the API?

You can customize the sender ID when sending SMS using the MSG91 API. However, the ability to use a custom sender ID depends on the country you're sending messages to.

An authentication key (Authkey), also known as an API key or access token, is a unique identifier or code that is used to authenticate and authorise requests made to the API. When making API requests, the authentication key is usually included in the request headers or as a query parameter.

It's important to handle authentication keys securely, as they can grant access to sensitive data or functionality.

1. Log in to the MSG91 panel. Select the Authkey option from the top row. You can also select it from the username dropdown or from the bottom left if you are inside any service dashboard.

2. Enter the registered mobile number and verify with the OTP you will receive on the registered number.

3. Click on the Create New option to create an authkey.

 4. The tab as shown below will get opened.

• Name the Authkey as per your preference. Please make sure there is no special character in this section.

• Select its use case in the "Where are you integrating" field or give a new one. 

• Select the Rule to be applied to that authkey from the Rules dropdown. For example, if permission for only selected services is given in the rule, then the authkey can only be used for those services. You can also create a new rule from the Rules section in the Settings of your account.

• The IP security is on by default. You can turn it off if required by editing the authkey settings. Whitelist your IPs in the Whitelist IPs field. The IPs whitelisted for the company will be visible under the Company's whitelisted IPs section at the bottom.

Once done, click on the Create button.

5. A new authentication key will be created and there will be an option to copy it. The IPs you whitelist in the Company's whitelisted IPs then they will be whitelisted for all the authkeys created in your MSG91 account. The Recent IPs will show you the IPs from which we have recently received the submissions from your account. You can whitelist them by the + icon given beside them.

Toggle the “Authkey status” option to disable your Authkey. You can enable the same by toggling again.

6. You can edit the authkey settings by the pencil icon under the Actions tab.

API SECURITY

It is an option that allows you to send your messages only through whitelisted IPs via API.

If API security is enabled and you try to send the SMS via any other IP then those requests will be rejected with

error code 418.

Let us begin with how you can enable the API Security in your account -

1. Log in to the MSG91 panel and select the Authkey option from the username dropdown. You can also access this dropdown from the bottom left if you are inside any service dashboard.

2. Enter the registered mobile number and verify with the OTP you will receive on the registered number.

3. Now, select the arrow under the Actions tab of the authkey you wish to enable the IP security in. You can enable/disable the IP security from the toggle. Enter the IPs that you wish to whitelist for that particular authkey in the Whitelisted IPs section. The IPs that you have whitelisted for the company will be visible under the Company's whitelisted IPs section at the bottom.

4. The IPs you whitelist in the Company's whitelisted IPs then they will be whitelisted for all the authkeys created in your MSG91 account. The Recent IPs will show you the IPs from which we have recently received the submissions from your account. You can whitelist them by the + icon given beside them.

NOTE:-

-> We support IPV6 & IPV4 addresses both. Eg: 2001:db8:3333:4444:5555:6666:7777:8888 (IPV6), 192.0. 2.146 (IPV4)

-> We strongly recommend you to keep it enabled as this provides an extra layer of security to your account.

-> If still you do not wish to have this security feature, you can disable it from the toggle in the authkey.

By doing so, the API will be called by any IP address that is not whitelisted, and MSG91 cannot be held liable for any spamming/fraudulent activities using the API.

How to check from which IP the API requests are failing -

1.  Goto the SMS section from your MSG91 Dashboard.

2. Select the Failed Logs section from the sidebar. The list of IPs by which the APIs got failed & you received the 418 error code is also available on the MSG91 Dashboard that you can copy & whitelist under Authkey section. 

3. Now, if you have enabled the Additional Security option. Enter at least one IP here. And press Yes on the popup window.

4. To whitelist more IPs, enter the IP address & click on Whitelist button.

2. Select the Failed Logs section from the sidebar. The list of IPs by which the APIs got failed & you received the 418 error code is also available on the MSG91 Dashboard that you can copy & whitelist under Authkey section. 

2. We always send alerts on your registered mail ID as well as mobile number, when the API gets failed with 418 error i.e. API security is enabled and you try to call the API via any other IP then, those requests will be rejected.

Note:-

-> We also send alerts on the registered email ID when any changes been made in API security option of your MSG91 account that is new IP is Added, any IP is Deleted, Additional Security is Enabled, and Additional Security is Disabled.

Need for Real-Time Response:

We understand that you might prefer receiving an error code directly in the API response, rather than a generic 200 Success response, to help you identify issues with your API in real time and make necessary adjustments promptly.

How It Works:

The real-time response feature provides the error code in the second attempt of the API call, not the first. This is because during the first API call, all the parameters you pass are validated, and a cache of this call is temporarily stored. The error code is then generated and displayed when you make the second API call with the same payload.

How to Use It:

To enable real-time response, include the parameter realTimeResponse=1 in your API call. This will ensure that the error code is returned in the API response during the second attempt.

Please note that this feature is not supported in our older API versions (v2).

Error Codes Returned:

The following error codes will be displayed in the real-time response:

201

203

301

306

308

400

401

403

418

For detailed descriptions of these error codes, please refer to the article:

API ERROR CODE

We hope this helps you use the real-time response feature effectively.

If you are using API and need to send a "+" sign in the content, you need to Double-encode the + sign in the message content.

Here is a sample code for PHP:

<?PHP

$message = "YOUR+++MESSAGE+++++WITH++++ PLUS++++SIGN";
$message = urlencode($message);
$message = urlencode($message);

//now the message is double-encoded

//send this message

?>

You can use this for encoding - 

https://meyerweb.com/eric/tools/dencoder/

Note: If you are unable to get the + sign with double encoding, try Triple encoding and then send the message.

DEBUG API 

There can be different reasons behind your API not working properly. We provide

 error codes

On hitting the API, if you face any issue, you can debug the API in the following manner:

Check the response received on calling the API.

1. If a 

   Request ID

   is generated on hitting the API, this means that your SMS is successfully submitted to MSG91. If your message gets failed due to any problem with API you can find the reason for the failure in the failed API section. If not, you can share the request ID with our 

   support team.

   
   
   

2. An error will be displayed instead of Request ID* if your SMS is not submitted successfully. You can find the reason behind it in our

   list of error codes 

   and remove the error accordingly. You may

    contact our support

   for any related query.

While submitting any request to our server we first generate the request ID and then process it further so at the same instance we will not be able to provide the exact reports of the ID and can only provide the below-mentioned status,

If the API is successfully submitted to our server the response is Type: "SUCCESS" and String: "REQUEST ID". 

For checking the complete reports, you need to check the delivery reports or can use

webhooks

Note: By default, you will get the response in string format but if you want to receive it in other formats (JSON, XML) then set this parameter. for example: &response=json or &response=xml

ERROR CODES

Error codes are displayed if there's an issue in the message sent by you. Click on the respective code to find out the reason for failed SMS and also to know what that particular code means.

You can also find the reasons for all the error codes for API below:

Use the placeholder for OTP in the message content as ##OTP## or if you are passing the value of OTP from your end then you need to put the same in the message as well.

In the Get method, kindly encode the ##OTP## and then pass the same in API, and in the Post method, you can directly pass ##OTP##.

Sample Get Method: 

http://control.msg91.com/api/sendotp.php?sender=MSGIND&authkey=Yourauthkey&message=your verification code is %23%23OTP%23%23&mobile=919999999999&DLT_TE_ID=111111111111111111

Sample OTP API with OTP value:

http://control.msg91.com/api/sendotp.php?authkey=authkey&mobiles=919999999999&sender=SENDER&otp=1234&DLT_TE_ID=1111111111111111111&message=1123 is your otp

For any further assistance, contact us at

[email protected]