16 Dec Send Single SMS Message Method

 

Send a message to only one recipient. The answer of the sent message is synchronous, meanwhile the delivery receipt of the message is asynchronous. (See Receive an Inbound SMS Message section).

To send a message the request must be submitted one of the following URLs:

HTTP (non-SSL)

HTTPS (SSL) *recommended*

 

2.1 HTTP Methods

For the Send SMS Message method, the POST HTTP method must be used.

2.2 Authentication Information

All requests require API Key and API Secret authentication credentials. Account Administrators can login to view their account API Key and API Secret in the “My Profile > Settings” section.

To authenticate a request, please use one of the following options:

In the header of the request for “apiKey

Parameter Name

apiKey

Description

The account’s API username (key). Its a 32 character random string.

Example:

 

Variable Type

String

Mandatory?

YES

 

In the header of the request for “apiSecret

Parameter Name

apiSecret

Description

The account’s API password (secret). Its a numeric random string with a random length between 10 and 15 characters.
Example:

 

Variable Type

String

Mandatory?

YES

 

In the body of the request (for POST-based requests only):

Parameter Name

apiAuthenticationData

Description

A JSON object for your apiKey and apiSecret.
Example:

 

Variable Type

Object

Mandatory?

YES

 

2.3 Request Parameters

 

Request Parameters for “to“:

Parameter Name

to

Description

The recipient (“to”) MSISDN.
The destination number must be in international format and contain only digit values (ex: 17858716500 when sending to the USA).

Variable Type

String

Mandatory?

YES

 

Request Parameters for “from“:

Parameter Name

from

Description

The Sender ID (“from”) to use in the SMS.
The Sender ID may be a telephone number (including country code) or it may be alphanumeric (ex: Telintel). If an alphanumeric string is used the maximum length is 11 characters. Destination restrictions may apply. Default= A generic, randomly generated number is used as the Sender ID.

Variable Type

String

Mandatory?

NO

 

Request Parameters for “message“:

Parameter Name

message

Description

The body of the SMS message.
Maximum length = 160 characters, some data encoding value maximum lengths may differ, please reference the datacoding

Variable Type

String

Mandatory?

YES

 

Request Parameters for “datacoding“:

Parameter Name

datacoding

Description

The alphabet to send the message, use as follows:

  • 1= ASCII (160 character max)
  • 2= ASCII Latin (160 character max)
  • 8= UTF-16 (70 character max)
  • Default = GSM 7 Bits codification (160 characters max)

Variable Type

Numeric, integer

Mandatory?

NO

 

Request Parameters for “from“:

Parameter Name

from

Description

The Sender ID (“from”) to use in the SMS.
The Sender ID may be a telephone number (including country code) or it may be alphanumeric (ex: Telintel). If an alphanumeric string is used the maximum length is 11 characters. Destination restrictions may apply.
Default= A generic, randomly generated number is used as the Sender ID.

Variable Type

String

Mandatory?

NO

The request body will contain a JSON object as following:

 

2.3.1 Examples using POST Method

 

PHP example

 

Java example (with Apache HTTPClient)

 

2.4 Response Parameters

 

Parameter Name

Description

Variable Type

responseType

An ENUM that represents the return code for the response.Please reference Response Codes table in Annex A. String

requestId

An integer that represents the reference ID of the request (all transactions). Integer

requestResponseId

An integer representing the return code of the response / error.Please reference Response Codes table in Annex A. Integer

requestResponseDescription

A human readable description of the transaction, related to the responseType attribute
Please reference Reponse Codes table in Annex A.

remainingBalance

Remaining account balance, after a message is sent. Double

to

Destination number where the message was sent String

messagePrice

Price of the sent message, based on the rates for the organization Double