Specification

API URL

URL used to send HTTP requests:

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

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

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 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	Yes	3600
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	null
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
Cache-Control: no-cache

{
    "application_id": "####",
    "application_token": "###########################################",
    "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.