## API URL URL used to send HTTP requests: ```url https://portal.bulkgate.com/api/1.0/integration/promotional ``` > [!NOTE] > If the request does not reach its destination, repeat it on the [backup server](https://www.bulkgate.com/en/docs/api-administration-tokens/api-backup-server/) `backup1.bulkgate.com`. ```http POST /api/1.0/integration/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ### Table with parameters | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:------------------|:--------------------------------------------------------|:---------:|:---------------------------------:| | application_id | [Application ID](https://www.bulkgate.com/en/docs/api-administration-tokens/api-administration/) | **Yes** | - | | application_token | [Application authentication token](https://www.bulkgate.com/en/docs/api-administration-tokens/api-tokens/) | **Yes** | - | | tag | Personal identification tag | No | - | | messages | Array of messages | **Yes** | [Message object](#message-object) | ### Message object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:---------------------------------------:| | primary_channel | The primary channel to be used first in the cascade | No | `sms` | | phone_number | Phone number of the recipient | **Yes** | - | | country | Provide recipient numbers in international format (with a prefix, e.g. `420`) or add [country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`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 information | No | `null` | | schedule | Schedule a time and date to send in [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) See examples below | No | `null` | | channels | Associative array of channel objects | **Yes** | [Channel object](#viber-channel-object) | ### Viber channel object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | sender | Sender name | No | - | | expiration | Time after which the message expires | No | `3600` | | button_caption | Button text | No | `OK` | | button_url | Button URL | No | `#` | | image | URL of the image contained in the message | No | `null` | | image_zoom | Can the image be zoomable? | No | `false` | | text | Message text. It is possible to add variables to the template from the `variables` array (another parameter) `Hello ....` | **Yes** | - | | variables | Associative array for adding variables to text e.g. `{"first_name": "John", "last_name": "Doe"}` | No | `[]` | ### SMS channel object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | sender_id | Sender ID, see [Sender ID type](#sender-id-type-sender-id) | No | `gSystem` | | sender_id_value | Value of the sender - `gOwn` (e.g. "420 777 777 777"), `gText` (e.g. "BulkGate"), `gProfile` (e.g. "423"), `gMobile` or `gPush` [(KEY)](https://www.bulkgate.com/en/helpdesk/mobile-connect/mobile-connect-install/) | No | `''` | | unicode | `Yes`/`true`/`1` for Unicode SMS, `no`/`false`/`0` for 7bit SMS | No | `false` | | text | SMS 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 ....` | **Yes** | - | | variables | Associative array for adding variables to the text e.g: `{"first_name": "John", "last_name": "Doe"}` | No | `[]` | #### Sender ID type `sender_id` | VALUE | DESCRIPTION | |:-----------|:----------------------------------------------------------------------| | `gSystem` | System number | | `gShort` | Short code | | `gText` | Text sender | | `gMobile` | [Mobile Connect](https://www.bulkgate.com/en/helpdesk/mobile-connect/mobile-connect-install/) | | `gPush` | Mobile Connect push - Sends a notification to your Mobile Connect app | | `gOwn` | Own number (requires number verification) | | `gProfile` | [Sender profile ID](https://www.bulkgate.com/en/helpdesk/sms/sender-id-profile/) | | `` | Sender profile ID | **Example of a complete request:** ```http-json POST /api/1.0/integration/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "button_caption": "OK", "button_url": "#", "image": "", "image_zoom": false, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "button_caption": "OK", "button_url": "#", "image": "", "image_zoom": false, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } } ] } ``` ## The response to this command can be: **In case of success** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 2, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "accepted", "message_id": "############-0", "part_id": [ "############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "accepted", "message_id": "############-1", "part_id": [ "############-1" ], "number": "420777777778", "channel": "sms" } ] } } ``` **In case of error:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } } ``` ```json { "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](https://www.bulkgate.com/en/docs/api-administration-tokens/api-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.](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/)