SMS API, Send HTTP SMS using API, PHP, Java Example Documentation

1.0 Getting Started

Our API resides at https://gauhatiuniversity.in/library/send_sms_2.php

1.1 Prior Checklist

You will have to prior things before using our API:

1. User and Password. If you are not an existing client, you can sign up at https://gauhatiuniversity.in

2. URL encoding of certain parameters.

1.2 Full URL for Message Sending

https://gauhatiuniversity.in/library/send_sms_2.php?UserName=username&Password=password&Type=Bulk&To=91xxxxxxxxxx&Mask=YourSenderid&Message=Hello%20Samir%2C%0APlease%20note%20our%20new%20number%0ARegards%0Ame%40me.com

Replace the parameters:

Username = Your Registered Username

Password = Your Registered Encoded Password

91xxxxxxxxxx = Your Recipient’s Mobile Number

YourSenderid = Your Approved Sender Name

Message =

Hello Samir,
Please note our new number...
Regards
[email protected]

 

Your URL Encoded Message as Hello%20Samir%2C%0APlease%20note%20our%20new%20number%0ARegards%0Ame%40me.com

 

1.3 SMS Message Encoding

The SMS Message needs to be URLENCODED which is also known as PERCENT ENCODING string of UTF-8 characters.

For more information on URL encoding, please see this: http://en.wikipedia.org/wiki/Percent-encoding

Above highlighted message in yellow is actually URLEncoded.

Actual Message content is (Original Message content)

Encoded Text:

Hello%20Samir%2C%0APlease%20note%20our%20new%20number%0ARegards%0Ame%40me.com

1.4 Default Parameters

 

Parameter

Value

Details

UserName

Account username provided by SMS Gateway

Username should be alphanumeric as assigned while creating account.

Password

URL Encoding of UTF8 Characters

The password must contain same as you use to login to SMS Gateway

v

1.1

Default Version is 1.1. (optional)

2.0 Send a Single SMS Message

You have seen the basic parameters and how you must include basic parameters with URL Encoding. Now, let us see how we can send a single SMS message using the API.

Currently SMS Gateway accepts plain text message with URL encoding.

 

2.1 SMS Message Parameters

Parameter

Value

Details

Type

Individual, Bulk, Group

Indicates the type of message, single, comma separated or group message

Language

English, Other

Optional to include language type, default is English.

To

Mobile Number of the recipient

This needs to be a pure numeric format without any special or alpha characters

Mask

Sender Name approved by SMS Gateway

6 Character sender name which is approved by SMS Gateway

Message

URL Encoded String of UTF-8 Characters

The content which needs to be sent and can contain alpha-numeric with special characters

Duplication

on/off (optional)

Default is on. This removes the duplicate mobile numbers to avoid sending multiple times.

 

2.2 Success Response

When Successful Request gets executed, then HTTP 200 Response will be generated.  The response to any SMS request is a string of tokens separated by pipe symbol (|).

A success response is

SUCCESS | Success (1) Fail (0) | Total Sms Cost (1)

This indicates that your request has been successfully submitted to operator.  Success (1) Fail (0) shows the number of mobiles included and Total Sms Cost (1) is basically SMS length message, if you include more than 160 characters then it will show Total Sms Cost (2)

2.3 Error Response

An error response is generated when it fails to validate the required parameter while sending SMS from API. It validates for all given parameters and some of them are listed below:

Username or password mismatch

error | 2115 | USERNAME OR PASSWORD IS INVALID

Type mismatch

error | 2116 | SMS SENDING TYPE IS UNKNOWN. PLEASE VERIFY.

Mobile Number mismatch

error | 2110 | PLEASE TYPE MOBILE NUMBER

Sender Name mismatch

error | 2107 | PLEASE ENTER THE SENDER ID

Empty Message content

error | 2108 | PLEASE TYPE YOUR MESSAGE

Operator downtime/unavailable

error | 2101 | SERVICE PROVIDER NOT AVAILABLE

Group Name mismatch

error | 2111 | PLEASE SELECT A GROUP

SMS Balance is 0

error | 2106 | NOT HAVING ENOUGH BALANCE TO SEND SMS

SMS Length Exceeded than assigned

error | 2119 | MAXIMUM SMS LENGTH EXCEEDED

User Account is blocked

error | 2113 | USER ACCOUNT HAS BEEN BLOCKED

User Account is expired

error | 2114 | USER ACCOUNT HAS BEEN EXPIRED

Gateway Closed

error | 999 | Gateway Closed

error | 912 | Gateway Closed

If parameter is not supported via API

error | 2220 | NOT SUPPORT VIA API

Multiple parameters mismatched

error | 2116 | SMS SENDING TYPE IS UNKNOWN. PLEASE VERIFY.

Excel File Writing Error

error | 2105 | UNKNOWN ERROR

Maximum SMS in Excel File

error | 2121 | SYSTEM ONLY SUPPORT (5000  OR 30000 OR 100000) SMS AT A TIME

Schedule date mismatch

error | 2104 | SCHEDULED DATE IS INVALID

Sender name or mobile number mismatch

error | 2126 | MASK OR MOBILE NO OR SMS LENGTH IS NOT VALID

2.4 Examples

Find the below example with two sending SMS types. One is sending plain text message and other is Unicode or other language SMS using API.

a)     Plain English Text

https://gauhatiuniversity.in/library/send_sms_2.php?UserName=userxxxx&Password=passxxxx&Type=Individual&To=9999999999&Mask=DEMO&Message=Hello%20Neha%2C%0ACall%20me%20on%20my%20number.%20I%20am%20looking%20for%20SMS%20Gateway%20in%20India.%0ARegards%0ASamir

 

Success Response: SUCCESS | Success (1) Fail (0) | Total Sms Cost (1)

Message Text on Recipient’s Mobile:

Hello Neha,

Call me on my number. I am looking for SMS Gateway in India.

Regards

Samir

 

b)     Other Language

https://gauhatiuniversity.in/library/send_sms_2.php?UserName=userdemo&Password=userxxxx9999999999&Mask=DEMO&Message=%E0%A4%8F%E0%A4%B8%E0%A4%8F%E0%A4%AE%E0%A4%8F%E0%A4%B8+%E0%A4%97%E0%A5%87%E0%A4%9F%E0%A4%B5%E0%A5%87+%E0%A4%87%E0%A4%82%E0%A4%A1%E0%A4%BF%E0%A4%AF%E0%A4%BE

 

Success Response: SUCCESS | Success (1) Fail (0) | Total Sms Cost (1)

Message Text on Recipient’s Mobile:

एसएमएस गेटवे इंडिया

3.0 Send Multiple Mobile Messages.

You can send SMS messages to multiple mobiles at once. Here is an example for sending Comma Separated Mobile Numbers.

https://gauhatiuniversity.in/library/send_sms_2.php?UserName=userxxx&Password=passxxxx&Type=Bulk&To=9999999999,9999999998,9999999997&Mask=DEMOSG&Message=Hello%20World

Response: SUCCESS | Success (3) Fail (0) | Total Sms Cost (3)

4.0 Send Group SMS

You can send SMS to your created group on our web SMS panel. For example, on www.smsgatewaycenter.com, you have created your group and added few contacts to that group then you can send SMS to that respective group.

https://gauhatiuniversity.in/library/send_group_sms.php?UserName=userxxxx&Password=passxxxx&Type=Group&Group=GroupName&Mask=Senderid&Duplication=on&Message=Hello%20World

Response: SUCCESS | Success (10) Fail (0) | Total Sms Cost (10)

5.0 Sample Codes

5.1 Sample PHP Code for sending SMS Message

<?php
$sendsms =""; //initialize the sendsms variable
$param[To] = "919xxxxxxxxx";
$param[Message] = "Hello World";
$param[UserName] = "userxxxx";
$param[Password] = "passxxxx";
$param[Mask] = "DEMOSG";
$param[v] = "1.1"; //optional
$param[Type] = "Individual"; //Can be "Bulk/Group”
//We need to URL encode the values
foreach($param as $key=>$val)
{
$sendsms.= $key."=".urlencode($val);
$sendsms.= "&"; //append the ampersand (&) sign after each parameter/value
}
$sendsms = substr($sendsms, 0, strlen($sendsms)-1);//remove last ampersand (&) sign from the sendsms
$url = "https://gauhatiuniversity.in/library/send_sms_2.php?".$sendsms;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$curl_scraped_page = curl_exec($ch);
curl_close($ch);
echo $curl_scraped_page;
?>

 


5.2 Sample JAVA Code for Sending SMS message

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URLEncoder;
import java.util.Date;
public class SMSGatewayCenterAPI {
public static void main(String[] args){
try {
Date mydate = new
Date(System.currentTimeMillis());
String data = "";
data += "Mask=DEMOSG";
data += "&UserName=userxxxx"; // your loginId
data += "&Password=" + URLEncoder.encode("passxxxx", "UTF-8"); // your password
data += "&Message=" + URLEncoder.encode("SMS Gateway message" + mydate.toString(), "UTF-8");
data += "&To=" + URLEncoder.encode("9999999999", "UTF-8"); // a valid 10 digit phone no.
data += "&v=1.1" ;
data += "&Type=Individual"; // Can be "Bulk" or "Group"
URL url = new
URL("https://gauhatiuniversity.in/library/send_sms_2.php?" + data);
HttpURLConnection conn = (HttpURLConnection)url.openConnection();
conn.setRequestMethod("GET");
conn.setDoOutput(true);
conn.setDoInput(true);
conn.setUseCaches(false);
conn.connect();
BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String line;
StringBuffer buffer = new StringBuffer();
while ((line = rd.readLine()) != null){
buffer.append(line).append("\n");
}
System.out.println(buffer.toString());
rd.close();
conn.disconnect();
}
catch(Exception e){
e.printStackTrace();
}
}
}

6.0 Miscellaneous

6.1 Delivery Report

https://gauhatiuniversity.in/library/deliveryreport.php?UserName=username&Password=password&DateFrom=2023-11-10&DateTo=2023-11-11

Date Format: yyyy-mm-dd

Delivery report is given with two parameters for status remarks.

1. Status

2. Cause

You will get status as SUCCESS OR FAIL and in Cause column, you will get all cause remarks whether delivered or failed cause as listed below.

 

List of Possible values for status and cause:

 

Status

Cause

SUCCESS

SUCCESS

FAIL

ABSENT SUBSCRIBER

UNKNOWN SUBSCRIBER

BLOCKED SENDERNAME

SYSTEM FAILURE

CALL BARRED

SERVICE DOWN

OTHER

DND FAIL

DND TIMEOUT

OUTSIDE WORKING HOUR

SUBMITTED

TIMEOUT

 

Cause Explanation:

--- ABSENT SUBSCRIBER: Operator could not reach the recipient.

--- UNKNOWN SUBSCRIBER: Unknown OR invalid number

--- BLOCKED SENDERNAME: Sender Name is blocked by SMS Gateway

--- SYSTEM FAILURE: Originating or Destination Operator system failure

--- CALL BARRED: Either operator or subscriber has blocked the number for unknown reasons.

--- SERVICE DOWN: Operator service is temporarily down.

--- OTHER: Message that are sent but could not be delivered for reasons that do not fall under any mentioned category

--- DND FAIL: Mobile number is DND database or does not want to receive messages being regular complaints.

--- DND TIMEOUT: Latest DND status is not available for the maximum 1 day time.

--- OUTSIDE WORKING HOUR: SMS Message sending is outside mentioned deliverable hours.

You can use the above URL and fetch the delivery report. Status gets updated every 2 hours for Promotional SMS route and every 30 minutes for Transactional SMS route.

6.2 Change Password

You can change password using API. URL is as follow:

https://gauhatiuniversity.in/library/change_password.php?Username=userxxxx&OldPassword=passxxxx&NewPassword=newpassxxxx

Success Response: SUCCESS | PASSWORD HAS BEEN CHANGED SUCCESSFULLY

Failure Response: error | 2115 | USERNAME OR PASSWORD IS INVALID

6.3 Check Balance

You can check your SMS balance using our API, URL is as follow:

https://gauhatiuniversity.in/library/checkbalance.php?Username=userxxxx&Password=passxxxx

Success Response: Balance : 2041 | Expire Date : 2023-09-30

Failure Response: error | 2115 | USERNAME OR PASSWORD IS INVALID

6.4 Miss Call Report

You can fetch all reports by using this API.

https://gauhatiuniversity.in/library/miscall_report.php?UserName=userxxxx&Password=passxxxx&DateFrom=2023-11-10&DateTo=2023-11-11

Note: Date Format: yyyy-mm-dd

You will get timestamp, recipient’s mobile number, circle, operator values.

6.5 Short code Report

You can fetch all your short code report using our API.

https://gauhatiuniversity.in/library/shortcode_report.php?UserName=userxxxx&Password=passxxxx&DateFrom=2023-11-10&DateTo=2023-11-11

Note: Date Format: yyyy-mm-dd

You will get timestamp, recipient’s mobile number, circle, operator values.

6.6 Opt in Users Report

You can fetch the opted recipient’s users list using our API.

https://gauhatiuniversity.in/library/optin_report.php?UserName=userxxxx&Password=passxxxx&DateFrom=2023-11-10&DateTo=2023-11-11

Note: Date Format: yyyy-mm-dd

You will get timestamp, recipient’s mobile number, circle, operator values.

6.7 Delivery Summary Report

Fetch daily SMS consumption summary using our API

https://gauhatiuniversity.in/library/delivery_summary_report.php?UserName=userxxxx&Password=passxxxx&DateFrom=2023-11-10&DateTo=2023-11-11

Note: Date Format: yyyy-mm-dd

You will get date, SMS consumed values.