Specification v2
API URL
URL used to send HTTP requests:
https://portal.bulkgate.com/api/2.0/advanced/promotional
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
Documentation of a previous version can be found here.
Parameters table
PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
---|---|---|---|
application_id | Application ID | Yes | - |
application_token | Application token | Yes | - |
number | Array of recipients - Value number | Yes or admins or groups | - |
groups | Array of numbers of groups in BulkGate address book. More info | Yes or number or admins | - |
admins | Array of numbers of BulkGate administrators receiving notifications. More info | Yes or number or groups | - |
text | Text of the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), UTF-8 encoding | Yes, if number is given by the array of numbers or the parameter groups or admin is used | - |
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 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. See examples below | No | Now |
duplicates_check | Select same_text to prevent sending duplicate messages to the same phone number. Disable the possibility to send a message with either the same or different text to the same number with same_number . If null no duplicates will be removed. | No | null |
number
Value The value number can be written in two ways:
- Array of phone numbers
[
"447820125799",
"447820100234",
"42060612345"
]
- Associative array with diagram
number
,text
, andvariables
, where the only required parameter isnumber
. Ifnumber
is not filled in, the message skips.
[
{"number": "447820125799", "text": "test1 <a>", "variables": {"a": 5}},
{"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}},
{"number": "42060612345", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
]
You can add variables from the array variables
into the template of parameter text
.
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. | 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
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 |
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. | 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 |
button | Mandatory structure that creates a button in the message | Yes | Button object |
image | Url to image | no | null |
Button object parameters table
PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
---|---|---|---|
caption | Button text | Yes | OK |
url | URL address | Yes | # |
Example of full request:
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
{
"application_id": "APPLICATION_ID",
"application_token": "APPLICATION_TOKEN",
"number": [
{"number": "447820125799", "text": "test1 <a>", "variables": {"a": 5}},
{"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}},
{"number": "42060612345", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
],
"groups": [1, 2],
"admins": [1, 4],
"text": "RCS: The future of mobile messaging for businesses",
"country": "cz",
"schedule": "2018-05-14T18:30:00-01:00",
"channel": {
"viber": {
"sender": "Lt. Hagan",
"expiration": 100,
"button": {
"caption": "Go To BulkGate",
"url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/"
},
"image": "https://www.bulkgate.com/wp-content/uploads/2023/06/rcs-rich-communication-services.jpg",
"text": "*RCS: The future of mobile messaging for businesses*\n\nEver found yourself wishing you could send more than just text in an SMS, like a high-resolution image or an interactive button? Or perhaps you wished for a read receipt just to confirm your message got through? Rich Communication Services (RCS) is here to revolutionize the way businesses communicate, enhancing your messaging experience and overcoming these limitations."
},
"sms": {
"sender_id": "gText",
"sender_id_value": "Lt-Hagan",
"unicode": true,
"text": "RCS: The future of mobile messaging for businesses"
}
}
}
Example of a request to enter recipients by the array of numbers and to schedule the time in the unix timestamp:
POST /api/2.0/advanced/promotional 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",
"447820100234",
"42060612345"
],
"text": "Hello, <first_name> <last_name>",
"schedule": "1526992636"
}
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":1,
"invalid_sender":0
}
},
"response":[
{
"status":"scheduled",
"sms_id":"idyrcmdd-0",
"part_id":[
"idyrcmdd-0_1",
"idyrcmdd-0"
],
"number":"420775123456",
"channel":"sms"
},
{
"status":"scheduled",
"sms_id":"idyrcmdd-1",
"part_id":[
"idyrcmdd-1_1",
"idyrcmdd-1"
],
"number":"420606123456",
"channel":"sms"
},
{
"status":"invalid_number",
"code":400,
"error":"Invalid phone number",
"detail":null,
"number":"44771447678",
"channel":"sms"
}
]
}
}
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.