Version 2.5C

Introduction

With MobiWeb Asynchronous SMS API you can send SMS messages with high throughput to 7+ billion subscribers of 1000+ Mobile Operators in 200+ countries.

The Asynchronous SMS API is based on REST. It uses built-in HTTP authentication and HTTP status codes. All data exchange is done in JSON format.

To test the Asynchronous SMS API, you will need a valid API account. If you don't have one yet, please contact us here to register for a FREE test account.

Authentication

https://[HOST]/apis/auth

Asynchronous SMS

https://[HOST]/apis/sms/mt/v2/

[HOST]

Replace [HOST] with your API account domain name or IP.

Asynchronous SMS Flow

To achieve better performance, messages you send With MobiWeb Asynchronous SMS API are validated and accepted instantly, but processed asynchronously. Once your messages are processed and submitted you will receive Status Notifications regarding the their status. Message Status Notifications are forwarded automatically, to your system / platform. When a message is processed by our SMS API Platform, the status information is immediately forwarded to your specified DLR Callback URL via a POST request (Status Notification Forwarding). After the messages are delivered or have reached their final status, our SMS API Platform immediately forwards the associated Delivery Reports to your specified DLR Callback URL via a POST request (DLR Forwarding).

API Flow

1st Step

Authentication with auth POST request.
2nd Step

Send messages with send POST request.
3rd Step

Receive Status Notifications through POST request to your specified DLR Callback URL.
4th Step

Receive Delivery Reports through POST request to your specified DLR Callback URL.

Authentication

Each request must be accompanied by a valid access_token. access_token are generated upon successful authentication. To authenticate you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value access_token , username and password.

access_token

If the request succeeded, an authentication object is returned, which includes an access_token and a refresh_token. Otherwise, an array of errors is returned. access_token grants you access to make requests.

Setup the Authorization HTTP header with your access_token. Authorization: Bearer dcec4eb6-035c-41a4-9871-82c5bd3ef379

access_token is valid for 30 minutes or for as long it is set through parameter validity, after which it expires. To preserve connection you must refresh with refresh_token. To reset connection please request a new access_token.

refresh_token

To refresh connection you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value "refresh_token" , refresh_token with value the refresh token, provided by a previously successful auth request.

Access from multiple nodes

When using multiple nodes to access API through the same account, please use parameter preserve to avoid each node resetting access_token, effectively blocking all other nodes from accessing the API.

Authentication

POST https://[HOST]/apis/auth

HTTP

POST https://[HOST]/apis/auth
Content-Type : application/json


{
 "type" : "access_token",
 "username" : "myusername",
 "password" : "mypassword"
}

{
 "status_code" : 200,
 "status_message" : "OK",
 "payload" : {
	 "access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
	 "validity_period" : 1800,
	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
}
}

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//Your account username and password
$username = "";
$password = "";

//Endpoint Options:
//  Client::SMPP_API_OTP_ENDPOINT - Asynchronous SMS API (SMS) - For (one-time pins) OTP & Notification messages
//  Client::SMPP_API_MRK_ENDPOINT - Asynchronous SMS API (SMS) - For marketing messages
$endpoint = MobiWeb\Rest\Client::SMPP_API_OTP_ENDPOINT;
	  
$client = new MobiWeb\Rest\Client($username, $password, $endpoint);

Refresh Connection

POST https://[HOST]/apis/auth
Content-Type : application/json


{
	 "type" : "refresh_token",
	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
}

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "access_token" : "0e3f6ecb-7a7e-4d03-a004-d710db8978ab",
	 	 "validity_period" : 1800,
	 	 "refresh_token" : "ecbb4d30-6da2-4b78-998e-d01025c648f2"
	 }
}

Send Single SMS

To send an sms you must send a send POST request.

https://[host]/apis/sms/mt/v2/send

Set parameters to with the the recipient mobile number phone in international E.164 format and from with your preferred sender.

Finally, setup parameter message with your message text.

Remember to setup the Authorization HTTP header with your access_token.

Congratulations! You just sent your first SMS using the Asynchronous SMS API.

If the request succeeded, an object is returned, which includes submission status and the information of the sms message. (Notice: No message id is provided at this step, as the message is not processed yet. Message id is provided with a successful message submission Status Notification forwarded to your specified DLR Callback URL, which you can use as reference to verify with the Delivery Report which you will receive for this message. If you need a unique identifier for this step, please set parameter reference_code, which is transmitted back to you in Status Notifications and Delivery Reports.) Otherwise, an array of errors is returned.

Each message has a status which includes the status for each message you attempted to send:

Send Message Status Codes

pending_processing

The message was accepted and will be processed immediately.
error

The message was not accepted. Please check attribute error for the reason(s).
scheduled

The message was accepted and will be sent at the specified datetime you have set in the schedule_date parameter.

Send Single SMS

POST https://[host]/apis/sms/mt/v2/send

HTTP

POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json


[
	{
		 "to" : ["447945223343"],
		 "from" : "HelloWorld",
		 "message" : "My first SMS message."
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "pending_processing",
			 "to" : "447945223343",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message."
		}
	 ]
}

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//Your account username and password
$username = "";
$password = "";

//Endpoint Options:
//  Client::SMPP_API_OTP_ENDPOINT - Asynchronous SMS API (SMS) - For (one-time pins) OTP & Notification messages
//  Client::SMPP_API_MRK_ENDPOINT - Asynchronous SMS API (SMS) - For marketing messages
$endpoint = MobiWeb\Rest\Client::SMPP_API_OTP_ENDPOINT;
	  
$client = new MobiWeb\Rest\Client($username, $password, $endpoint);
//Submit message
$message = $client->broadcast(
	[[
		"from" => "HelloWorld", //The sender displayed upon the SMS arrival. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
		"to" => ["44xxxxxxxxxx"], //The full international number(s) of the recipient(s) in international E.164 format https://en.wikipedia.org/wiki/E.164.
		"message" => "Hello from MobiWeb!" //The text of the SMS message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_/_GSM_03.38, you can send up to 160 characters in a single SMS. You can send longer messages automatically by setting message parameter with your preffered text. In long SMS (multi-part SMS), each SMS part can be up to 153 characters. Each part costs as 1 SMS. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table https://en.wikipedia.org/wiki/UTF-16, because of the increased memory requirement for each character, you can send up to 70 characters in a single SMS. In long SMS (multi-part SMS), each SMS part can be up to 67 characters. Each part costs as 1 SMS.
	]]
);

//Print message
print_r($message);

All Options

//Your account username and password
$username = "";
$password = "";

$client = new MobiWeb\Rest\AsynchClient($username, $password);
//Submit message
$message = $client->broadcast(
	[[
		"from" => "HELLO", //The sender displayed upon the SMS arrival. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
		"to" => ["44xxxxxxxxxx"], //The full international number(s) of the recipient(s) in international E.164 format https://en.wikipedia.org/wiki/E.164.
		"message" => "Hello from MobiWeb!" //The text of the SMS message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_/_GSM_03.38, you can send up to 160 characters in a single SMS. You can send longer messages automatically by setting message parameter with your preffered text. In long SMS (multi-part SMS), each SMS part can be up to 153 characters. Each part costs as 1 SMS. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table https://en.wikipedia.org/wiki/UTF-16, because of the increased memory requirement for each character, you can send up to 70 characters in a single SMS. In long SMS (multi-part SMS), each SMS part can be up to 67 characters. Each part costs as 1 SMS.
		"options" => [
			"receive_dlr" => "1", //Set this parameter to ‘1’ for requesting delivery report for this SMS. Refer to receive status notifications and delivery Reports section for more information. https://api.solutions4mobiles.com/asynchronous-sms-api.html#receive_status_notifications
			"message_type" => "sms", //The type of the SMS message.
			"reference_code" => "ABCD1234", //Set this parameter to your preferred reference id / custom data for this submission. Length can be up to 50 characters.
			"schedule_date" => "2021-06-16 13:06:00", //Set this parameter in format "yyyy-mm-dd hh:mm:ss" UTC +0 to schedule your sending to a future datetime. Must be at least 20 minutes from now.
			"expire_date" => "2021-06-16 15:00:00" //Set this parameter in format "yyyy-mm-dd hh:mm:ss" UTC +0 to force expiration of your SMS to a future datetime. Must be at least 30 minutes from now and schedule_date.
		]
	]]
);

//Print message
print_r($message);

Multilingual Support

POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json


[
	{
		 "to" : ["8613054782931"],
		 "from" : "HELLO",
		 "message" : "早上好我的朋友"
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "Pending Processing",
			 "to" : "8613054782931",
			 "from" : "HELLO",
			 "message" : "早上好我的朋友"
		}
	 ]
}

Receive Status Notifications

Status Notifications of messages processed are forwarded automatically, to the user system / platform. When a message is processed by our SMS API Platform, the status information is immediately forwarded to your specified DLR Callback URL via a POST request. Data are transmitted in JSON format.

To setup your DLR Callback URL please contact support

https://[DLR Callback URL]

Status Notification POST request transmits the message id, reference_code ( cross-check with reference_code you used with your send POST requests or cross-check with recipient phone ), recipient phone and message status.

Only messages that are successfully submitted are charged.

SMS API Platform will stop sending Status information of a SMS when it accepts a HTTP Status Code 200 from the user’s system. HTTP Status Code 200 is considered as a valid acknowledgement of Status information from the user side.

SMS API Platform will send Status Notifications every 5 seconds for 24 hours, when the information is discarded by the system regardless of successfull delivery to your system.

There are multiple message submission status codes:

Submission Status Codes

SUBMITTED

The message was submitted successfully.
ERROR_SUBMITTING

The message was not submitted.

Receive Status Notifications

HTTP

POST https://[DLR Callback URL]
Content-Type : application/json


{
     "phone" : "447945223343",
     "reference_code" : "FH832JR0REW1F0",
     "id" : "4bff9ce7692344a8b6e5968b95e09db5",
     "status" : "SUBMITTED"
}

HTTP/1.1 200 OK

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//For information about receiving status notifications please visit https://api.solutions4mobiles.com/asynchronous-sms-api.html#receive_status_notifications

//Get request
$inputJSON = file_get_contents('php://input');

//convert JSON into array
$input = json_decode($inputJSON, TRUE);

//Print data
print_r($input);

//Return successful http code
header('HTTP/1.1 200 OK', TRUE, 200);
//or error
//header('HTTP/1.1 500 Internal Server Error', true, 500);

Receive Delivery Reports

Delivery reports are forwarded automatically, to the user system / platform. When an SMS delivery report is received by our SMS API Platform, the DLR information is immediately forwarded to your specified DLR Callback URL via a POST request. Data are transmitted in JSON format.

To setup your DLR Callback URL please contact support

https://[DLR Callback URL]

DLR forwarding POST request transmits the delivery report date, message id ( cross-check with id you received from the Status Notification request), reference_code, recipient phone and message status.

SMS API Platform will stop sending DLR information of a SMS when it accepts a HTTP Status Code 200 from the user’s system. HTTP Status Code 200 is considered as a valid acknowledgement of DLR information from the user side.

SMS API Platform will send Delivery Reports every 5 seconds for 24 hours, when the information is discarded by the system regardless of successfull delivery to your system.

There are multiple message submission status codes:

Submission Status Codes

DELIVERED

Message delivered.
UNDELIVERED

Message could not be delivered.
REJECTED

Message rejected.
EXPIRED

Message expired.

Receive Delivery Reports

HTTP

POST https://[DLR Callback URL]
Content-Type : application/json


{
     "date" : "2018-08-22 19:00:21",
     "phone" : "447945223343",
     "reference_code" : "FH832JR0REW1F0",
     "id" : "4bff9ce7692344a8b6e5968b95e09db5",
     "status" : "DELIVERED"
}

HTTP/1.1 200 OK

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//For information about receiving delivery reports please visit https://api.solutions4mobiles.com/asynchronous-sms-api.html#receive_delivery_reports

//Get request
$inputJSON = file_get_contents('php://input');

//convert JSON into array
$input = json_decode($inputJSON, TRUE);

//Print data
print_r($input);

//Return successful http code
header('HTTP/1.1 200 OK', TRUE, 200);
//or error
//header('HTTP/1.1 500 Internal Server Error', true, 500);

Get Balance

To get your account's balance you must send a balance GET request.

https://[host]/apis/sms/mt/v2/balance

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account balance. Otherwise, an error is returned.

Get Balance

GET https://[host]/apis/sms/mt/v2/balance

HTTP

GET https://[host]/apis/sms/mt/v2/balance
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
			 "balance" : "7845.3500"
	 }
}

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//Your account username and password
$username = "";
$password = "";

//Endpoint Options:
//  Client::SMPP_API_OTP_ENDPOINT - Asynchronous SMS API (SMS) - For (one-time pins) OTP & Notification messages
//  Client::SMPP_API_MRK_ENDPOINT - Asynchronous SMS API (SMS) - For marketing messages
$endpoint = MobiWeb\Rest\Client::SMPP_API_OTP_ENDPOINT;
	  
$client = new MobiWeb\Rest\Client($username, $password, $endpoint);

//Get account balance and print it
echo $client->getBalance();

Get Pricing

To get your account’s pricing details and covered networks, you must make a pricing GET request.

https://[host]/apis/sms/mt/v2/pricing

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account currency and an array of network objects with coverage and pricing information. Network objects have attributes operator id, operator countryname, operatorname, operator mobile country code mcc, operator mobile network code mnc and your acount price per SMS sent to this network. Otherwise, an error is returned.

Get Pricing

GET https://[host]/apis/sms/mt/v2/pricing

HTTP

GET https://[host]/apis/sms/mt/v2/pricing
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
		 {
			  "id" : 473,
			  "countryname" : "Afghanistan",
			  "operatorname" : "Roshan",
			  "mcc" : "412",
			  "mnc" : "020",
			  "price" : "0.0190"
		 },
		 ..............
		 ]
	 }
}

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//Your account username and password
$username = "";
$password = "";

//Endpoint Options:
//  Client::SMPP_API_OTP_ENDPOINT - Asynchronous SMS API (SMS) - For (one-time pins) OTP & Notification messages
//  Client::SMPP_API_MRK_ENDPOINT - Asynchronous SMS API (SMS) - For marketing messages
$endpoint = MobiWeb\Rest\Client::SMPP_API_OTP_ENDPOINT;
	  
$client = new MobiWeb\Rest\Client($username, $password, $endpoint);

//Get account pricing and print it
print_r($client->getPricing(MobiWeb\Rest\Client::SMS));

Errors

SMS API uses 2 levels of errors. Conventional HTTP status codes and application error codes.

SMS API raises errors for many reasons (authentication, invalid parameters, network / server errors etc.). Consult the detailed HTTP status codes and application error codes tables for detailed explanation of response codes.

Please notice that HTTP status code 200 OK does not always result to a successful request. Always consult payload or errors objects to ensure that you interpret result correctly.

Application Errors

SMS API returns errors in an array of objects.

Object Attributes

code numeric

Application error code identifying error.
message string

A human-readable message providing more details about the error.

Errors

{
	 "status_code" : 401,
	 "status_message" : "Unauthorized",
	 "errors" : [
		{
			 "code" : 1005,
			 "message" : "Invalid refresh token"
		}
	 ]
}

HTTP Status Codes

200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to invalid JSON format.
401	Unauthorized	No valid API key provided.
404	Not Found	The requested resource doesn't exist.
422	Unprocessable Request	The request unprocessable, often due to invalid parameters.
500	Internal Server Error	The service is temporarily unavailable.

Application Error Codes

1001	Invalid token type	Invalid parameter.
1004	Invalid authentication credentials	Credentials provided is not correct.
1005	Invalid refresh token	Invalid parameter.
1006	Insufficient balance	User balance is not enough in order to process the request.
1009	Invalid access token	Access token is invalid.
1200	Invalid parameter (from)	Invalid parameter. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-) or 14 numeric characters (0-9). Special characters are not allowed.
1202	Invalid message	Invalid parameter.
1203	Invalid parameter (to)	Invalid parameter.
1215	Invalid schedule_date - Format: yyyy-mm-dd hh:mm:ss	Invalid parameter.
1216	Parameter schedule_date must be after now	Parameter schedule_date must be after now.
1217	Invalid expire_date - Format: yyyy-mm-dd hh:mm:ss	Invalid parameter.
1218	Parameter expire_date must be after schedule_date	Parameter expire_date must be after schedule_date.
1219	Parameter expire_date must be after now	Parameter expire_date must be after now.
1222	Service is not available	Service is temporarily unavailable.
1223	Error submitting SMS	Service is temporarily unavailable.

The AUTH Request

POST

The auth request is used to authenticate and gain access to the SMS API requests.

Parameters

type required predefined string "access_token" , "refresh_token"

The type of the auth request. Can be "access_token" to reset connection or "refresh_token" to refresh connection.
validity optional (Default 1800) numeric

The number of seconds that the access_token will be valid.
preserve optional (Default false) boolean true , false

Preserve an access_token if it already exists and it is not expired. Used when multiple nodes use the same account to access the API.
username required for type "access_token" string

The username of your SMS API account.
password required for type "access_token" string

The password of your SMS API account.
refresh_token required for type "refresh_token" string

The refresh_token. Used when refreshing the connection.

Response

If the request succeeds, an authentication object is returned. An access_token for SMS API requests and a refresh_token to refresh the connection are provided. Returns an array of errors on failure.

Object Attributes

access_token string

The access_token to use with the SMS API requests.
validity_period numeric

The validity period of access_token and refresh_token.
refresh_token string

The refresh_token to use when refreshing the connection.

/auth

POST https://[HOST]/apis/auth

POST https://[HOST]/apis/auth
Content-Type : application/json


{
	 "type" : "access_token",
	 "username" : "myusername",
	 "password" : "mypassword"
}

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
	 	 "validity_period" : 1800,
	 	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
	 }
}

The SEND Request

POST

The send request is used to send a single or multiple SMS messages.

Request

The request body must be an array of objects, each one representing an SMS with one or multiple recipients.

Parameters

to required array

The full international number(s) of the recipient(s) in international E.164 format.
from required string

The sender displayed upon the SMS arrival. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
message_type optional (Default "sms") predefined string "sms"

The type of the SMS message.
message required for "sms" string

The text of the SMS message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table, you can send up to 160 characters in a single SMS. You can send longer messages automatically by setting message parameter with your preffered text. In long SMS (multi-part SMS), each SMS part can be up to 153 characters. Each part costs as 1 SMS. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table, because of the increased memory requirement for each character, you can send up to 70 characters in a single SMS. In long SMS (multi-part SMS), each SMS part can be up to 67 characters. Each part costs as 1 SMS.
receive_dlr optional (Default 1) predefined numeric 0 , 1

Set this parameter to ‘1’ for requesting delivery report for this SMS. Refer to receive Delivery Reports section for more information .
schedule_date optional (Default NOW) date

Set this parameter in format "yyyy-mm-dd hh:mm:ss" UTC +0 to schedule your sending to a future datetime. Must be after now.
expire_date optional date

Set this parameter in format "yyyy-mm-dd hh:mm:ss" UTC +0 to force expiration of your SMS to a future datetime. Must be after now and after schedule_date.
reference_code optional string

Set this parameter to your preferred reference code / custom data for this submission. Length can be up to 50 characters.

Response

If the request succeeds, an array of objects is returned. One object is returned per one to (recipient). Returns an array of errors on failure.

Respone object attributes vary, depending on the message_type of the SMS submission.

Object Attributes :: sms

status predefined string "pending_processing" , "scheduled" , "error"

The result status of SMS submission.
to numeric

The recipient's phone number in international E.164 format.
from string

The sender to display upon the SMS arrival.
message_type predefined string "sms"

The message type.
message string

The SMS message text.
schedule_date date

The future date that the system will send the SMS.
expire_date date

The date that the SMS will expire and will not be sent, in case of a queue / delay.
receive_dlr numeric 0 , 1

Indicates if a DLR was requested for this submission.
reference_code string

The reference code / custom data for this submission.

/send

Send SMS

POST https://[host]/apis/sms/mt/v2/send

POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json


[
	{
		 "to" : ["447945223343","447945223342","447945223341"],
		 "from" : "HelloWorld",
		 "message" : "My first SMS message.",
		 "receive_dlr" : 1,
		 "message_type" : "sms",
		 "schedule_date" : "2015-05-12 13:30:00",
		 "expire_date" : "2015-05-12 14:30:00",
         "reference_code" : "ref_34235345435-435435"
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "pending_processing",
			 "to" : "447945223343",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message.",
			 "receive_dlr" : 1,
			 "message_type" : "sms",
			 "schedule_date" : "2015-05-12 13:30:00",
			 "expire_date" : "2015-05-12 14:30:00",
			 "reference_code" : "ref_34235345435-435435"
		},
		{
			 "status" : "pending_processing",
			 "to" : "447945223342",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message.",
			 "receive_dlr" : 1,
			 "message_type" : "sms",
			 "schedule_date" : "2015-05-12 13:30:00",
			 "expire_date" : "2015-05-12 14:30:00",
			 "reference_code" : "ref_34235345435-435435"
		},
		{
			 "status" : "pending_processing",
			 "to" : "447945223341",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message.",
			 "receive_dlr" : 1,
			 "message_type" : "sms",
			 "schedule_date" : "2015-05-12 13:30:00",
			 "expire_date" : "2015-05-12 14:30:00",
			 "reference_code" : "ref_34235345435-435435"
		}
	 ]
}

The BALANCE Request

GET

The balance GET request is used to get an account's balance.

Response

If the request succeeds, an object with the current account's balance is returned. Returns an array of errors on failure.

Object Attributes

balance string

The balance of your account.

/balance

GET https://[host]/apis/sms/mt/v2/balance

GET https://[host]/apis/sms/mt/v2/balance
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
			 "balance" : "7845.3500"
	 }
}

The PRICING Request

GET

The pricing GET request is used to get your account’s pricing details and covered networks.

Response

If the request succeeds, an object is returned, which includes your account currency and an array of network objects with coverage and pricing information. For an operator with multiple MNCs, a separate record will be displayed for each one. Returns an array of errors on failure.

Object Attributes

currency object

currency object.
- name string
  
  The name of your account's currency.
- symbol string
  
  The symbol of your account's currency.
pricing array

Array of pricing objects.
- id numeric
  
  Mobile network operator id.
- countryname string
  
  Mobile network operator country.
- operatorname string
  
  Mobile network operator name.
- mcc string
  
  Mobile country code of mobile operator.
- mnc string
  
  Mobile network code of mobile operator.
- price string
  
  Price per SMS for this mobile operator.

/pricing

GET https://[HOST]/apis/sms/mt/v2/pricing

GET https://[host]/apis/sms/mt/v2/pricing
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
         {
            "id" : 473,
            "countryname" : "Afghanistan",
            "operatorname" : "Roshan",
            "mcc" : "412",
            "mnc" : "020",
            "price" : "0.0190"
         },
         ..............
		 ]
	 }
}

Examples

Version 2.5C

Introduction

Authentication

Asynchronous SMS

[HOST]

Asynchronous SMS Flow

API Flow

1st Step

2nd Step

3rd Step

4th Step

Authentication

access_token

refresh_token

Access from multiple nodes

Authentication

Refresh Connection

Send Single SMS

Send Message Status Codes

pending_processing

error

scheduled

Send Single SMS

All Options

Multilingual Support

Receive Status Notifications

Submission Status Codes

SUBMITTED

ERROR_SUBMITTING

Receive Status Notifications

Receive Delivery Reports

Submission Status Codes

DELIVERED

UNDELIVERED

REJECTED

EXPIRED

Receive Delivery Reports

Get Balance

Get Balance

Get Pricing

Get Pricing

Errors

Application Errors

Object Attributes

code numeric

message string

Errors

HTTP Status Codes

Application Error Codes

The AUTH Request

Parameters

type required predefined string "access_token" , "refresh_token"

validity optional (Default 1800) numeric

preserve optional (Default false) boolean true , false

username required for type "access_token" string

password required for type "access_token" string

refresh_token required for type "refresh_token" string

Response

Object Attributes

access_token string

validity_period numeric

refresh_token string

/auth

The SEND Request

Request

Parameters

to required array

from required string

message_type optional (Default "sms") predefined string "sms"

message required for "sms" string

receive_dlr optional (Default 1) predefined numeric 0 , 1

schedule_date optional (Default NOW) date

expire_date optional date

reference_code optional string

Response

Object Attributes :: sms

status predefined string "pending_processing" , "scheduled" , "error"

to numeric

from string