Specification

API URL

URL used to send HTTP requests:

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

POST /api/1.0/integration/transactional-bulk 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 NAMEVALUEMANDATORYDEFAULT VALUE
application_idApplication IDYes-
application_tokenApplication authentication tokenYes-
tagPersonal identification tagNo-
messagesArray of messagesYesMessage object

Message object

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
primary_channelThe primary channel to be used first in the cascadeNosms
phone_numberPhone number of the recipientYes-
countryProvide 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 informationNonull
scheduleSchedule a time and date to send in unix timestamp. See examples below.Nonull
channelsAssociative array of channel objectsYesChannel object

Viber channel object

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
senderSender nameNo-
expirationTime after which the message expiresYes3600
textMessage text. It is possible to add variables to the template from the variables array (another parameter) Hello <first_name> <last_name> ....Yes-
variablesAssociative array for adding variables to text e.g. {"first_name": "John", "last_name": "Doe"}No[]

SMS channel object

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
sender_idSender ID, see Sender ID typeNogSystem
sender_id_valueValue of the sender - 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
textSMS 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-
variablesAssociative array for adding variables to the text e.g: {"first_name": "John", "last_name": "Doe"}No[]

Sender ID type sender_id

VALUEDESCRIPTION
gSystemSystem number
gShortShort code
gTextText sender
gMobileMobile Connect
gPushMobile Connect push - Sends a notification to your Mobile Connect app
gOwnOwn number (requires number verification)
gProfileSender profile ID
<int>Sender profile ID

Example of a complete request:

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

{
  "application_id": "####",
  "application_token": "######################################",
  "tag": "",
  "messages": [
    {
      "primary_channel": "sms",
      "phone_number": "420777777777",
      "country": "cz",
      "schedule": 1683101313,
      "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"
          }
        }
      }
    },
    {
      "primary_channel": "sms",
      "phone_number": "420777777778",
      "country": "cz",
      "schedule": 1683101313,
      "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": {
        "total": {
            "status": {
                "sent": 0,
                "accepted": 0,
                "scheduled": 2,
                "error": 0,
                "blacklisted": 0,
                "invalid_number": 0,
                "invalid_sender": 0
            }
        },
        "response": [
            {
                "status": "scheduled",
                "message_id": "#############-0",
                "part_id": [
                    "#############-0"
                ],
                "number": "420777777777",
                "channel": "sms"
            },
            {
                "status": "scheduled",
                "message_id": "#############-1",
                "part_id": [
                    "#############-1"
                ],
                "number": "420777777778",
                "channel": "sms"
            }
        ]
    }
}

In case of error:

{
    "data": {
        "total": {
            "status": {
                "sent": 0,
                "accepted": 0,
                "scheduled": 0,
                "error": 0,
                "blacklisted": 0,
                "invalid_number": 0,
                "invalid_sender": 0
            }
        },
        "response": []
    }
}

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

← SpecificationSpecification →