Try for free

Transactional SMS – specification (Advanced API)

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 message, please contact our support. We may allow this option for good cause.

API URL

The URL used to send the HTTP requests:

https://portal.bulkgate.com/api/2.0/advanced/transactional

Note

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

Supported HTTP methods

POST - application/json

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

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`	-
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 tried in a cascade, in the order in which you list them in the object - if we are unable to deliver your message via the first channel, the next one in the list is used. SMS is not appended automatically; if you want it as the last fallback, include the `sms` object in the cascade. When no channel is given at all, the message is sent as SMS.	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

The channel object decides which channels the message is sent through and in what order. The order of the keys in your request is the order of the cascade and SMS is not appended to it automatically - see Channel cascade.

KEY	CHANNEL OBJECT
`sms`	SMS
`viber`	Viber – transactional
`rcs`	RCS
`whatsapp`	WhatsApp

Request example

POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "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

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 }

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.

Was this page helpful?

Ask AI Copied