Send Message API- Post – Knowledgebase : SMSstream

SMSstream offers simple to use REST API that you can easily integrate with your application to send notification messages, alerts, confirmation and verification SMS and all sort of important short business messages. From Banks, mobile wallets to tracking companies, our Send Message API is best suitable for the service providers that require delivering important information on right time to the right users/customers.

The following article discusses Send Message API that you can use to send message from SMSstream’s gateway. The article includes sample codes, with both successfully and possible erroneous responses. Before you submit your API request, make sure that you have generated a valid API Token for your account. Following are other set of requirements that you need to have for submitting API request

Parameter and Values

Parameter	Type	Value
End Point	Required	Portal.smsstream.com/api
Authentication	Required	Your valid API token
Mobile Number (Parameter)	Required	Put forward mobile number of the contact; and make sure you follow the standard number format.
Sender ID (Parameter)	Required	If you have an active Sender ID approved by the admin, use it here to send your message from. Or, use default Sender ID (SMSstream) in case you don’t have a sender ID approved.
Message (Parameter)	Required	Your message text here.

Standard Number Format

Number format that SMSstream follows is Country Code (971 for UAE), Network Prefix (50 Etisalat) and Mobile Number. Example entry of a mobile number of United Arab Emirates would look like, 97150XXXXXXX, Pakistan would look 92333XXXXXXX . .

Maximum Characters for One SMS

Make sure that 160 characters is the maximum length of one SMS, exceeding from the maximum length will concatenate the message on recipient’s end, and an extra credit will be deducted from your account. Every message with 160 character length is measured one SMS, and exceeding from 160 characters will charge you an extra credit for another 160 character limit.

Sample API Request

Following Post request is set to send “Test Message” from the default sender ID “SMSstream” to specific contact number in the Mobile Number string.

Request (Post)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

function sendMessage($sParam) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://portal.smsstream.com/api');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer Valid_API_Token_Here'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $sParam);
$result = curl_exec($ch);
if ($result === false) {
echo curl_error($ch);
}
curl_close($ch);
return $result;
}
$sParam = array(
'mobile_no' => '92333XXXXXXX',
'sender_id' => 'SMSstream',
'message' => 'Test Message'
);
echo $response = sendMessage($sParam);

Successful Response

Upon hitting correct API Endpoint, with valid API token and all required parameters filled, following Json based response will return.

Status value for the successfully executed request will be- “sent”

Data Returned-“Message ID” and “Mobile Number”

Following is the success response upon send the above mentioned request.

1	{"mobile_no":"92333XXXXXXX","message_id":"2b24bdfa-f846-4f43-9bbc-dd36630b4a49","status":"sent"}}

Erroneous Responses

If you submit request with some inappropriate or wrong information, you will get the error response, following area discusses few erroneous responses.

When used an invalid/wrong API Token, it will give authorization error.

1	Authorization Failed

When submitting a request with wrongly used parameter (mobile_no , sender_id, message)

1	Invalid Parameter

Sample Error Request

Following request illustrates that a wrongly formatted/invalid number is added in mobile-number parameter.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

function sendMessage($sParam) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://portal.smsstream.com/api');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer Valid_API_Token_Here'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $sParam);
$result = curl_exec($ch);
if ($result === false) {
echo curl_error($ch);
}
curl_close($ch);
return $result;
}
$sParam = array(
'mobile_no' => '92333873778544',
'sender_id' => 'SMSstream',
'message' => 'Test Message'
);
echo $response = sendMessage($sParam);

Response

Status Value- Failed
Data Returned- Mobile Number
Description- Text based message describing reason of mobile number failure
Here is how the response will look like…

1	{"mobile_no":"929595acecesd","status":"failed","description":"Invalid Number String"}

Banned Words

SMSstream categorizes some of the words/terms as spam and thus ban these words to relay through from the gateway. You can learn more about banned words by clicking the following link.

So if you have used one or more banned words in your message parameter while submitting API request, your message will be blocked and the following response will return.

Status Value- Failed
Data Returned- Mobile Number
Descripiton- Text based message providing banned word(s) that causes failure

1	{"mobile_no":"92333xxxxxxx","status":"failed","description":"Sending failed due to banned word","banned_words":"profit"}