Transactional messages – specification

API URL

URL used to send HTTP requests:

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

Note

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

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

Caution

It is strictly prohibited to exploit transactional SMS for promotional/marketing uses. It must be used for notification purposes only - as an SMS notification.

Note

If you would like to use a transactional route to send a bulk notification messages, please contact our support. We may allow this option for good cause.

Warning

Recipients who have unsubscribed will receive the message (opt-out applies to promotional messages only).

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	-
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
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	`false`

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/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "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": { "status": "accepted", "message_id": "omni-############", "part_id": [ "omni-##############" ], "number": "420777777777", "channel": "sms" } }

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 (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