Specification v2
API URL
The URL used to send the HTTP requests:
https://portal.bulkgate.com/api/2.0/advanced/transactional
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
Documentation of a previous version can be found here
It is strictly prohibited to exploit transactional SMS for promotional/marketing uses. It must be used for notification purposes only - as an SMS notification.
If you would like to use a transactional route to send a bulk notification message, please contact our support. We may allow this option for good cause.
Parameters table
| PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
|---|---|---|---|
| application_id | Application indentificator | Yes | - |
| application_token | Application authentication token | Yes | - |
| number | Recipient number or array of recipient numbers - Value number | Yes or admins or groups | - |
| text | Text of SMS message (max. 612 characters, or 268 characters if Unicode is used), 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 | [] |
| channel | Alternative channels. Channels are listed in a cascade, if we are unable to deliver your message via highest priority channel, channels lower in the cascade list will be used. If none of them manages to deliver sms will be used instead. | No | SMS object |
| country | Provide the recipients' numbers in an international format (with prefix, e.g. 44) or add the country code in ISO 3166-1 alpha-2 format (7820125799 + GB = 447820125799). See the country example request. If null, your set timezone will be used to fill 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 minutes. If off no duplicates will be removed. | No | off |
Value number
The value number can be written as follows:
- Array of phone numbers
[
"447820125799",
"447820100234",
"42060612345"
]
SMS object parameters table
| PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
|---|---|---|---|
| text | Text of SMS message (max. 612 characters, or 268 characters if Unicode is used), UTF-8 encoding. It is possible to add variables to the template from the variables array (another parameter) Hello <first_name> <last_name> .... | Yes, if general text isn't used. If SMS object contains text parameter as well as general text parameter, SMS text will be used instead | - |
| 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 |
| unicode | Yes/true/1 for Unicode SMS, no/false/0 for 7bit SMS | No | false |
Sender ID type sender_id
| VALUE | DESCRIPTION |
|---|---|
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 (number verification required) |
gProfile | BulkGate Profile ID |
<int> | BulkGate Profile ID |
Viber object parameters table
| PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
|---|---|---|---|
| text | Text of SMS message (max. 612 characters, or 268 characters if Unicode is used), UTF-8 encoding. It is possible to add variables to the template from the variables array (another parameter) Hello <first_name> <last_name> .... | Yes, if general text isn't used. If Viber object contains text parameter as well as general text parameter, Viber text will be used instead | - |
| sender | Sender | Yes | "" |
| expiration | Time limit after which alternative channel will be used | No | 120 |
Example of full request:
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
{
"application_id": "********",
"application_token": "**************",
"number": ["777777777", "777777778"],
"text": "example text <first_name>",
"variables": {"first_name": "John"},
"country": "cz",
"schedule": "2023-08-14T18:30:00-01:00",
"channel": {
"viber": {
"sender": "BulkGate",
"expiration": 100
},
"sms": {
"sender_id": "gText",
"sender_id_value": "Mr. Sender",
"unicode": true
}
}
}
Response to this command may be:
In case of success:
{
"data": {
"total": {
"status": {
"sent": 0,
"accepted": 0,
"scheduled": 2,
"error": 0,
"blacklisted": 0,
"invalid_number": 0,
"invalid_sender": 0,
"duplicity_message": 0
}
},
"response": [
{
"status": "scheduled",
"message_id": "transactional-64afe5f28ffc2-0",
"part_id": [
"transactional-64afe5f28ffc2-0"
],
"number": "420777777777",
"channel": "viber"
},
{
"status": "scheduled",
"message_id": "transactional-64afe5f28ffc2-1",
"part_id": [
"transactional-64afe5f28ffc2-1"
],
"number": "420777777778",
"channel": "viber"
}
]
}
}
Where:
- part_ID is the ID array of the parts of the original long message that were split because they did not meet the 160 character limit for a single message. More info here.
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.