Specification 1.0
API URL
URL used to send HTTP requests:
https://portal.bulkgate.com/api/1.0/advanced/transactional
POST /api/1.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
It is strictly prohibited to exploit SMS notification for promotional/marketing uses. It must be used for notification purposes only - as a transactional SMS.
Parameters table
PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
---|---|---|---|
application_id | Application ID | Yes | - |
application_token | Application token | Yes | - |
number | Recipient number | Yes or admin | - |
admin | Number of BulkGate administrator receiving notification. More info | Yes or number | - |
text | Text of the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), UTF-8 encoding. It is possible to add variables to the template from the variables array (another parameter) Hello <first_name> <last_name> .... | Yes | - |
variables | Associative array to add variables to text, for e.g.: {"first_name": "John", "last_name": "Doe"} | No | [] |
unicode | Yes /true /1 for Unicode SMS, no /false /0 for 7bit SMS | No | false |
sender_id | Sender ID, see Sender ID type | No | gSystem |
sender_id_value | Sender value - gOwn (e.g. "420 777 777 777"), gText (e.g. "BulkGate"), gProfile (e.g. "423"), gMobile or gPush (KEY) | No | null |
country | Provide recipient numbers in international format (with prefix, for e.g 44 ), or add country code (7820125799 + GB = 447820125799 ). See the example of a country requirement. If the value is null, your set time zone will be used to fill in the information | No | null |
schedule | Schedule the sending time and date in unix timestamp, or ISO 8601. | No | Now |
duplicates_check | Select on to prevent sending duplicate messages to the same phone number. Messages with the same text sent to the same number will be removed if there is a time interval shorter than 5 mins. If off no duplicates will be removed. | No | off |
tag | Message label for subsequent retrieval of the user. | No | - |
sender_id
Sender ID type VALUE | MEANING |
---|---|
gSystem | System number |
gShort | Short Code |
gText | Text sender |
gMobile | Mobile Connect |
gPush | Mobile Connect push - Sends a notification to the Mobile Connect app |
gOwn | Own number (requires number verification) |
gProfile | BulkGate Profile ID |
<int> | BulkGate Profile ID |
Example of full request:
POST /api/1.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
{
"application_id": "APPLICATION_ID",
"application_token": "APPLICATION_TOKEN",
"number": "447820125799",
"unicode": true,
"text": "Hello, <first_name> <last_name>",
"variables": {"first_name": "John", "last_name": "Doe"},
"sender_id": "gText",
"sender_id_value": "BulkGate",
"country": "cz",
"schedule": "2018-05-14T18:30:00-01:00"
}
Response to this command may be:
In case of success:
{
"data": {
"status": "accepted",
"sms_id": "tmpde1bcd4b1d1",
"price": 0.02,
"credit": 215.81380,
"number": "447820125799"
}
}
In case of error:
{
"type": "invalid_phone_number",
"code": 400,
"error": "Invalid phone number",
"detail": null
}
{
"type": "unknown_identity",
"code": 401,
"error": "Unknown identity / unauthorized / empty application_id",
"detail": null
}
Where:
- type and error (description of the error) can be found in the error types table,
- code represents http error
- detail is an additional info about the error
See all the error types for Simple API and Advanced API here.