BulkGate Helpdesk
  • Languages iconEnglish
    • Czech

›Promotional SMS

Transactional SMS

  • Specification 2.0
  • Specification 1.0
  • Sending message to notification admin

Promotional SMS

  • Specification 2.0
  • Specification 1.0
  • Sending messages to groups from address book
  • Sending messages to notification admins

Check credit balance

  • Check credit balance

API Administration & Tokens

  • API administration & tokens

Error types

  • Error types

Delivery confirmations and incoming SMS

  • Delivery confirmations and incoming SMS
  • Bulk delivery confirmation of incoming SMS

Specification 2.0

API URL

URL used to send HTTP requests:

https://portal.bulkgate.com/api/2.0/advanced/promotional
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

Documentation of a previous version can be found here.

Parameters table

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
application_idApplication IDYes-
application_tokenApplication tokenYes-
numberArray of recipients - Value numberYes or admins or groups-
groupsArray of numbers of groups in BulkGate address book. More infoYes or number or admins-
adminsArray of numbers of BulkGate administrators receiving notifications. More infoYes or number or groups-
textText of the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), UTF-8 encodingYes, if number is given by the array of numbers or the parameter groups or admin is used-
channelAlternative 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.NoSMS object
countryProvide recipient numbers in international format (with prefix, for e.g 44), or add country code (7820125799 + GB = 447820125799). See the example of a country requirement. If the value is null, your set time zone will be used to fill in the informationNonull
scheduleSchedule the sending time and date in unix timestamp, or ISO 8601. See examples belowNoNow
duplicates_checkSelect 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.Nonull

Value number

The value number can be written in two ways:

  • Array of phone numbers
[
    "447820125799",
    "447820100234", 
    "42060612345"
]
  • Associative array with diagram number,text, and variables', where the only required parameter is number. Ifnumber` is not filled in, the message skips.
[
    {"number": "447820125799", "text": "test1 <a>", "variables": {"a": 5}},
    {"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}},
    {"number": "42060612345", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
]

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

SMS object parameters table

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
textText of SMS message (max. 612 characters, or 268 characters if Unicode is used), UTF-8 encoding.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_idSender ID, see sender ID typeNogSystem
sender_id_valueSender value - gOwn (e.g. "420 777 777 777"), gText (e.g. "BulkGate"), gProfile (e.g. "423"), gMobile or gPush (KEY)Nonull
unicodeYes/true/1 for Unicode SMS, no/false/0 for 7bit SMSNofalse

Sender ID type sender_id

VALUEMEANING
gSystemSystem number
gShortShort Code
gTextText sender
gMobileMobile Connect
gPushMobile Connect push - Sends a notification to the Mobile Connect app
gOwnOwn number (requires number verification)
gProfileBulkGate Profile ID
<int>BulkGate Profile ID

Viber object parameters table

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
textText of SMS message (max. 612 characters, or 268 characters if Unicode is used), UTF-8 encoding.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-
senderSenderYes""
expirationTime limit after which alternative channel will be usedNo120
buttonMandatory structure that creates a button in the messageYesButton object

Button object parameters table

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
captionButton textYesOK
urlURL addressYes#

Example of full request:

POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "APPLICATION_ID",
    "application_token": "APPLICATION_TOKEN",   
    "number": [
        {"number": "447820125799", "text": "test1 <a>", "variables": {"a": 5}},
        {"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}},
        {"number": "42060612345", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
    ],
    "groups": [1, 2],
    "admins": [1, 4],
    "text": "Hello, <first_name> <last_name>",
    "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"
        }
        }
}

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

{
    "application_id": "APPLICATION_ID",
    "application_token": "APPLICATION_TOKEN",   
    "number": [
        "447820125799",
        "447820100234", 
        "42060612345"
    ],
    "text": "Hello, <first_name> <last_name>",
    "schedule": "1526992636"
}

Response to this command may be:

In case of success:

{
  "data": {
    "total": {
      "price": 0.0522,
      "status": {
        "sent": 0,
        "accepted": 0,
        "scheduled": 2,
        "error": 1
      }
    },
    "response": [
      {
        "status": "scheduled",
        "sms_id": "tmpde1f00539c7",
        "price": 0.0261,
        "credit": 215.81380,
        "number": "447820125799"
      },
      {
        "status": "scheduled",
        "sms_id": "tmpde1f0053f0c",
        "price": 0.0261,
        "credit": 215.81380,
        "number": "447820100234"
      },
      {
        "status": "error",
        "code": 9,
        "error": "Invalid phone number",
        "number": "42060612345"
      }
    ]
  }
}

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.

← Sending message to notification adminSpecification 1.0 →
  • API URL
    • Parameters table
    • Value number
    • SMS object parameters table
    • Viber object parameters table
    • Button object parameters table
  • Response to this command may be:
SolutionsSMS GatewayViber for BusinessBroadcastBulk SMSSMS NotificationsTwo-way SMSMobile ConnectWeb Portal
Partners & DevelopersSMS APIIntegrationsAffiliate programWhite label
SourcesBlogYouTubeFacebookLinkedInTwitterGitHubPackagist
CompanyContactPrivacyTerms and Conditions
Price listsPrice list SMSPrice list ViberPrice list Mobile Connect
SMS GatewayTOPefekt s.r.o. © 2023