Specification 2.0

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.

Parameters table

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
application_id	Application indentificator	Yes	-
application_token	Application authentication token	Yes	-
number	Recipient number	Yes	-
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 (7820125799 + GB = 447820125799). 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

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

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_token": "******************************",
    "application_product": "http-advanced",
    "number": "420111222333",
    "text": "example text <first_name>",
    "variables": {"first_name": "Lt. Mosley"},
    "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"
      }
    }
}

Response to this command may be:

In case of success:

{
    "data": {
        "status": "accepted",
        "sms_id": "tmpde1bcd4b1d1",
        "price": 0.02,
        "credit": 215.81380,
        "number": "447700900000"
    }
}

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.