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

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

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

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

{
     "phone" : "447945223343",
     "reference_code" : "FH832JR0REW1F0",
     "id" : "4bff9ce7692344a8b6e5968b95e09db5",
     "status" : "SUBMITTED"
}
HTTP/1.1 200 OK

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

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

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
GET https://[host]/apis/sms/mt/v2/balance
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
			 "balance" : "7845.3500"
	 }
}

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
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"
		 },
		 ..............
		 ]
	 }
}

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 true) boolean false , true

    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"
	}
]
{
	 "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"
		},
		{
			 "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"
		},
		{
			 "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"
		}
	 ]
}

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"
         },
         ..............
		 ]
	 }
}