Promotional SMS – specification (Advanced API)

API URL

URL used to send HTTP requests:

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

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/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Parameters table

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
application_id	Application ID	Yes	-
application_token	Application token	Yes	-
number	Array of recipients - Value number	Yes or `admins` or `groups`	-
groups	Array of numbers of groups in BulkGate address book. More info	Yes or `number` or `admins`	-
admins	Array of numbers of BulkGate administrators receiving notifications. More info	Yes or `number` or `groups`	-
text	Text of the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), UTF-8 encoding	Yes, if `number` is given by the array of numbers or the parameter `groups` or `admin` is used	-
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 recipient numbers in international format (with prefix, for e.g `44`), or add country code (`777777777` + `GB` = `44777777777`). See the example of a country requirement. If the value is `null,` your set time zone will be used to fill in the information	No	`null`
schedule	Schedule the sending time and date in unix timestamp, or ISO 8601. See examples below	No	Now
duplicates_check	Select `same_text` to prevent sending duplicate messages to the same phone number. Disable the possibility to send a message with either the same or different text to the same number with `same_number`. If `null` no duplicates will be removed. Duplicates are removed within a single batch only, not across requests.	No	`null`
tag	Message label for subsequent retrieval of the user.	No	-

Value `number`

The value number can be written in two ways:

Array of phone numbers

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

Associative array with diagram number, text, and variables, where the only required parameter is number. If number is not filled in, the message skips.

[ {"number": "420777777777", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ]

You can add variables from the array variables into the template of parameter text.

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 – promotional
`rcs`	RCS
`whatsapp`	WhatsApp

Request examples

Example of full request:

POST /api/2.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ {"number": "420777777777", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ], "groups": [1, 2], "admins": [1, 4], "text": "RCS: The future of mobile messaging for businesses", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "Lt. Hagan", "expiration": 100, "button": { "caption": "Go To BulkGate", "url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/" }, "image": "https://www.bulkgate.com/assets/illustrations/rcs-rich-communication-services.jpg", "text": "*RCS: The future of mobile messaging for businesses*\n\nEver found yourself wishing you could send more than just text in an SMS, like a high-resolution image or an interactive button? Or perhaps you wished for a read receipt just to confirm your message got through? Rich Communication Services (RCS) is here to revolutionize the way businesses communicate, enhancing your messaging experience and overcoming these limitations." }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true, "text": "RCS: The future of mobile messaging for businesses" } } }

Example of a request to enter recipients by the array of numbers and to schedule the time in the unix timestamp:

POST /api/2.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ "420777777777", "420888888888", "420999999999" ], "text": "Hello, <first_name> <last_name>", "schedule": "1526992636" }

Response

In case of success:

{ "data":{ "total":{ "status":{ "sent":0, "accepted":0, "scheduled":2, "error":0, "blacklisted":0, "invalid_number":1, "invalid_sender":0 } }, "response":[ { "status":"scheduled", "sms_id":"idyrcmdd-0", "part_id":[ "idyrcmdd-0_1", "idyrcmdd-0" ], "number":"420777777777", "channel":"sms" }, { "status":"scheduled", "sms_id":"idyrcmdd-1", "part_id":[ "idyrcmdd-1_1", "idyrcmdd-1" ], "number":"420888888888", "channel":"sms" }, { "status":"invalid_number", "code":400, "error":"Invalid phone number", "detail":null, "number":"420999999999", "channel":"sms" } ] } }

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