Specification v2 · BulkGate Helpdesk

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 `admin` or `groups`	-
admin	Number of BulkGate administrator receiving notification. More info	Yes or `number`	-
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 (`777777777` + `GB` = `44777777777`). 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`
tag	Message label for subsequent retrieval of the user.	No	-

Value `number`

The value number can be written as follows:

Array of phone numbers

[
    "420777777777",
    "420888888888", 
    "420999999999"
]

Channels table

Table of all supported alternative channels

VALUE	DESCRIPTION
`sms`	SMS channel object
`viber`	Viber channel object
`rcs`	RCS channel object
`whatsapp`	WhatsApp channel object

SMS object

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

Important — transactional Viber messages (effective 1 July 2026): Every transactional Viber message must be sent through an approved template (use_template: true + a valid template_id). This applies to all traffic, including international. Without a valid template_id, the message is delivered as a raw Viber message. There is no automatic conversion from a raw send to a template send.

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
text	Text of the Viber message (raw message body). If `use_template` is `true` with a valid `template_id`, the template content is delivered instead and this field is ignored for Viber. Without a template, `text` is sent as a raw Viber message. If both the Viber object `text` and the general `text` are set, the Viber `text` is used.	Yes, if general `text` isn't used	–
sender	Sender.	Yes	`""`
expiration	Time limit (in seconds) after which the alternative channel will be used.	No	`120`
use_template	Whether the message is sent using a preapproved transactional template. Set to `true` and provide a valid `template_id` to send as a template. If `false` or no valid `template_id` is provided, the message is sent as a raw Viber message. For a promotional message, leave `false` and omit the template fields.	No (required as `true` for transactional messages)	`false`
template_id	Id of the preapproved template. Required whenever `use_template` is `true`. If omitted, the message is delivered as raw Viber content.	No (required if `use_template` is `true`)	`null`
template_language	Language variant of the given preapproved template. Must match the template's language.	No	`en`
template_parameters	Object with the variables defined in the selected template. Keys must exactly match the template's variable names. Pass an empty object `{}` for a static template that has no variables.	No	`[]`

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_ID",
    "application_token": "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": {
        "whatsapp": {
            "sender": "420777777777",
            "expiration": 300,
            "message": {
                "text": "text"
            }
        },
        "rcs": {
            "sender": "BulkGate",
            "expiration": 300,
            "message": {
                "text": "text"
            }
        },
        "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
}