Developer Docs

Table of contents

Sending SMS

PUT (POST is also supported) /sms/create

Creating single SMS (“destination”:”phone”), bulk messaging (“destination”:”phones”) and customized SMS (“destination”:”individual”) are supported. In the future, the possibility to create a messaging via the API from the address book will be added (“destination”:”addresbook”).

The payload parameter passed for “destination”:”phone” containing a JSON-encoded array having the following structure:

Sample code:

PUT (POST)

Endpoint URL: https://api.bsg.hk/rest/sms/create

Header:

X-API-KEY: live_qwefqw41234
Content-type: application/json

JSON Body RAW:

{
"destination":"phones", 
"phones":[
{"msisdn": "85226010227","reference":"12erdgm9"},
{"msisdn": "85236016161","reference":"12erdgn0"}
],
"originator":"test",
"body":"test sms", 
"validity": 72,
"tariff":9, 
"send_time" : "ISO 8601 date"
}

The following parameters are passed:

Required:

  • destination – set to the “phones” value
  • phones – values array:
  • msisdn – the phone number to which the SMS is sent
  • reference – SMS external ID. String up to 32 characters containing /a-zA-Z0-9/
  • originator – sender. String up to 14 characters
  • body – Message text. Text

Optional:

  • validity – SMS validity time (by default – 72 hours). Integer from 1 to 72
  • tariff – tariff number. The default is 0. An integer from 0 to 9
  • send_time – time of sending SMS (for SMS messaging scheduling)

In this case, an example of the correct response / Response: 

{
"result":
[
{"reference":"12erdgm9",
"id":"12345",
"error":"0",
"price":"0.02",
"currency":"EUR"},
{"reference":"12erdgn0",
"id":"12346",
"error":"0",
"price":"0.02",
"currency":"EUR"}
],
"error":"0", 
"totalprice":"0.04",
"currency":"EUR",
"task_id":"21902"
}

The task_id parameter is intended for the status request on the entire messaging.

If the data contains an error, a response will be returned approximately as follows:

{
"error":"25",
"errorDescription":"Invalid originator"
}

For the scenario destination = individual

{
"validity": 72,
"tariff":9, 
"destination":"individual", 
"phones":
[
{"originator":"test1",
"body":"test sms1", 
"msisdn":"85226010227",
"reference": "12erdgm9"},
{"originator":"test2",
"body":"test sms2",
"msisdn": "85211025454",
"reference": "12erdgn0"}
], 
"scheduledDatetime" : "ISO 8601 date"
}

The following parameters are passed (optional are italicised):

  • destination – set to the “phones” value
  • validity – SMS validity time (by default – 72 hours). Integer from 1 to 72
  • tariff – tariff number. The default is 0. An integer from 0 to 9
  • phones – values array:
  • msisdn – the phone number to which the SMS is sent
  • reference – SMS external ID. String up to 32 characters containing /a-zA-Z0-9/
  • originator – sender. String up to 14 characters
  • body – Message text. Text
  • scheduledDatetime – time of sending SMS (for SMS messaging scheduling)

In this case, example of the correct response:

{
"result":
[
{"reference":"12erdgm9",
"id":"12345",
"error":"0",
"price":"0.02",
"currency":"EUR"},
{"reference":"12erdgn0",
"id":"12346",
"error":"0",
"price":"0.02",
"currency":"EUR"}
],
"error":"0", 
"totalprice":"0.04",
"currency":"EUR",
"task_id":"21902"
}

The task_id parameter is intended for the status request on the entire messaging.

If the data contains an error, a response will be returned approximately as follows:

{
"error":"24",
"errorDescription":"Invalid request payload"
}

We use cookies (and other similar technologies) to collect data to improve your experience on our site. By using our website, you’re agreeing to the collection of data as described in our Website Data Collection Policy.