## API URL URL used to send HTTP requests: ```url https://portal.bulkgate.com/api/1.0/integration/transactional ``` > [!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/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!CAUTION] > It is **strictly prohibited** to exploit [transactional SMS](https://www.bulkgate.com/en/helpdesk/general-information/difference-promotional-transactional-sms/) for promotional/marketing uses. It must be used for notification purposes only - as an SMS notification. > [!NOTE] > If you would like to use a transactional route to send a bulk notification messages, please contact [our support.](https://www.bulkgate.com/en/contact-us/) 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 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 | - | | 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) | | duplicates_check | Select **`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. | No | `false` | ### 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/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "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": { "status": "accepted", "message_id": "omni-############", "part_id": [ "omni-##############" ], "number": "420777777777", "channel": "sms" } } ``` **In case of error:** ```json { "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null } ``` ```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/)