BulkGate Helpdesk
  • Languages iconEnglish
    • Czech

›Transactional SMS

Transactional SMS

  • Specification v2
  • Specification v1
  • Sending message to notification admin

Promotional SMS

  • Specification v2
  • Specification v1
  • Sending messages to groups from address book
  • Sending messages to notification admins

Price and credit information

  • Check credit balance
  • Information about the price of the message

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 v2

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.

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.

Parameters table

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
application_idApplication indentificatorYes-
application_tokenApplication authentication tokenYes-
numberRecipient number or array of recipient numbers - Value numberYes or admins or groups-
textText 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-
variablesAssociative array to add variables to text, for e.g.: {"first_name": "John", "last_name": "Doe"}No[]
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 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 informationNonull
scheduleSchedule the sending time and date in unix timestamp, or ISO 8601.NoNow
duplicates_checkSelect 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.Nooff

Value number

The value number can be written as follows:

  • Array of phone numbers
[
    "447820125799",
    "447820100234", 
    "42060612345"
]

SMS object parameters table

PARAMETER NAMEVALUEMANDATORYDEFAULT VALUE
textText 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_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

VALUEDESCRIPTION
gSystemSystem number
gShortShort Code
gTextText sender
gMobileMobile Connect
gPushMobile Connect push - Sends a notification to the Mobile Connect app
gOwnOwn Number (number verification required)
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. 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-
senderSenderYes""
expirationTime limit after which alternative channel will be usedNo120

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": "**************",
    "number": ["777777777", "777777778"], 
    "text": "example text <first_name>",
    "variables": {"first_name": "John"},
    "country": "cz",
    "schedule": "2023-08-14T18:30:00-01:00",
    "channel": {
      "viber": {
        "sender": "BulkGate",
        "expiration": 100
      },
      "sms": {
        "sender_id": "gText",
        "sender_id_value": "Mr. Sender",
        "unicode": true
      }
    }
}

Response to this command may be:

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.

Specification v1 →
  • API URL
    • Parameters table
    • Value number
    • SMS object parameters table
    • Viber 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