Promotional messages – specification

API URL

URL used to send HTTP requests:

https://portal.bulkgate.com/api/1.0/integration/promotional

Note

If the request does not reach its destination, repeat it on the backup server backup1.bulkgate.com.

POST /api/1.0/integration/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Table with parameters

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
application_id	Application ID	Yes	-
application_token	Application authentication token	Yes	-
tag	Personal identification tag	No	-
messages	Array of messages	Yes	Message object

Message object

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
primary_channel	The primary channel to be used first in the cascade	No	`sms`
phone_number	Phone number of the recipient	Yes	-
country	Provide recipient numbers in international format (with a prefix, e.g. `420`) or add country code (`775123456` + `CZ` = `420775123456`). Look at an example of a country's requirement. If the value is `null,` then your set time zone is used to complete the information	No	`null`
schedule	Schedule a time and date to send in unix timestamp, See examples below	No	`null`
channels	Associative array of channel objects	Yes	Channel object

Viber channel object

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
sender	Sender name	No	-
expiration	Time after which the message expires	No	`3600`
button_caption	Button text	No	`OK`
button_url	Button URL	No	`#`
image	URL of the image contained in the message	No	`null`
image_zoom	Can the image be zoomable?	No	`false`
text	Message text. It is possible to add variables to the template from the `variables` array (another parameter) `Hello <first_name> <last_name> ....`	Yes	-
variables	Associative array for adding variables to text e.g. `{"first_name": "John", "last_name": "Doe"}`	No	`[]`

SMS channel object

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
sender_id	Sender ID, see Sender ID type	No	`gSystem`
sender_id_value	Value of the sender - `gOwn` (e.g. "420 777 777 777"), `gText` (e.g. "BulkGate"), `gProfile` (e.g. "423"), `gMobile` or `gPush` (KEY)	No	`''`
unicode	`Yes`/`true`/`1` for Unicode SMS, `no`/`false`/`0` for 7bit SMS	No	`false`
text	SMS text (max. 612 characters or 268 characters if Unicode is enabled), UTF-8 encoding. It is possible to add variables to the template from the `variables` array (additional parameter) `Hello <first_name> <last_name> ....`	Yes	-
variables	Associative array for adding variables to the text e.g: `{"first_name": "John", "last_name": "Doe"}`	No	`[]`

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 your Mobile Connect app
`gOwn`	Own number (requires number verification)
`gProfile`	Sender profile ID
`<int>`	Sender profile ID

Example of a complete request:

POST /api/1.0/integration/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "button_caption": "OK", "button_url": "#", "image": "", "image_zoom": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "button_caption": "OK", "button_url": "#", "image": "", "image_zoom": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } } } } ] }

The response to this command can be:

In case of success

{ "data": { "total": { "status": { "sent": 0, "accepted": 2, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "accepted", "message_id": "############-0", "part_id": [ "############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "accepted", "message_id": "############-1", "part_id": [ "############-1" ], "number": "420777777778", "channel": "sms" } ] } }

In case of error:

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } }

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

Where:

type and error (error description) can be seen in table of error types
code represents http error
detail is additional information about error

All error types for Simple API and Advanced API can be found here.

Was this page helpful?

Ask AI Copied