Press ⌘ + K to search

API

APIs



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:

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 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

How can I integrate SMS API
Jan 21, 2025

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.




Where can I find my authentication key?
Nov 11, 2024

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.










What do you mean by API Security?
Nov 11, 2024

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.

What is a Real-Time Response and How Does It Work?
Nov 30, 2024


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.


How to send + sign in SMS from API?
Nov 11, 2024


DEBUG API 


There can be different reasons behind your API not working properly. We provide error codes according to the reason for API failure. 


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.


How to debug if my API is not working?
Nov 11, 2024


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 to get the delivery details in real-time for the same, and during the case of Failed API, an email is sent to your registered ID mentioning the error code and its description.


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

How to get SMS status in API?
Nov 11, 2024

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:



101

Missing mobile number

102

Missing message

104

Missing username

105

Missing password

201

Invalid username or password. 201 also appears in case the XML code triggered is incorrect.

202

Invalid mobile number

203

Invalid sender ID or DLT Entity Id Missing

207

Invalid authentication key

208

IP is blacklisted

209

Default route not found

210

The route could not be determined. Please contact support

211

DLT Template Id Missing

301

The user does not have sufficient balance to send SMS

302

Expired user account

303

Banned user account

306

This route is currently unavailable

307

The schedule time is incorrect

308

Campaign name cannot be more than 32 characters

309

The selected group(s) does not belong to you

310

SMS is too long. The system paused this request automatically

311

When the same SMS content is sent to the same number within 10 seconds. This is a security feature used to avoid multiple deliveries. The first SMS will be delivered and the second will be rejected. The balance will also be deducted only once.

400

Flow ID Missing or Invalid Flow

401

Flow Not Yet Approved

402

The message has some hard block keywords.

403

Flow is disabled

418

IP not whitelisted

421

Service Terminated (Please reach out to your account manager or write to [email protected])

506

Internal error, please contact your account manager

601

Internal error, please contact your account manager

602

If your current route is disabled, kindly select another route

603

This sender ID is blacklisted, please use a different sender ID

604

Please enter at least one correct number to send an SMS

606

The scheduled date cannot be more than three weeks

607

Please enter the campaign name

608

Scheduled SMS cannot be less than the current end time

What are the reason for error codes received under the API failed?
Nov 11, 2024


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]. 

How do resolve the error OTP not found and placeholder not found in the message?
Nov 11, 2024