Specification 2.0 · BulkGate Helpdesk

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`

Value `number`

The value number can be written in two ways:

Array of phone numbers

[
    "447820125799",
    "447820100234", 
    "42060612345"
]

Associative array with diagram number,text, and variables', where the only required parameter is number. 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 type `sender_id`

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

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": "Hello, <first_name> <last_name>",
    "country": "cz",
    "schedule": "2018-05-14T18:30:00-01:00",
    "channel": {
        "viber": {
            "sender": "Lt. Hagan",
            "expiration": 100,
            "text": "example text"
        },
        "sms": {
            "sender_id": "gText",
            "sender_id_value": "Lt-Hagan",
            "unicode": true,
            "text": "example text"
        }
        }
}

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": {
      "price": 0.0522,
      "status": {
        "sent": 0,
        "accepted": 0,
        "scheduled": 2,
        "error": 1
      }
    },
    "response": [
      {
        "status": "scheduled",
        "sms_id": "tmpde1f00539c7",
        "price": 0.0261,
        "credit": 215.81380,
        "number": "447820125799"
      },
      {
        "status": "scheduled",
        "sms_id": "tmpde1f0053f0c",
        "price": 0.0261,
        "credit": 215.81380,
        "number": "447820100234"
      },
      {
        "status": "error",
        "code": 9,
        "error": "Invalid phone number",
        "number": "42060612345"
      }
    ]
  }
}

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.