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
Maximum Characters for One SMS
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"} |