> [!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 message, please contact [our support.](https://www.bulkgate.com/en/contact-us/) We may allow this option for good cause. ## API URL The URL used to send the HTTP requests: ```url https://portal.bulkgate.com/api/2.0/advanced/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`. ## Supported HTTP methods - `POST` - `application/json` ```http POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Parameters table | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------:|:------------------------------------------:| | application_id | [Application indentificator](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** | - | | number | Recipient number or array of recipient numbers - [Value number](#value-number) | **Yes** or `admin` | - | | admin | Number of BulkGate administrator receiving notification. [More info](https://www.bulkgate.com/en/docs/advanced-api/advanced-transactional-admin/) | **Yes** or `number` | - | | text | Text 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 ....` | **Yes** | - | | variables | Associative array to add variables to text, for e.g.: `{"first_name": "John", "last_name": "Doe"}` | No | `[]` | | channel | Alternative channels. Channels are tried in a cascade, in the order in which you list them in the object - if we are unable to deliver your message via the first channel, the next one in the list is used. SMS is **not** appended automatically; if you want it as the last fallback, include the `sms` object in the cascade. When no channel is given at all, the message is sent as SMS. | No | [SMS object](https://www.bulkgate.com/en/docs/advanced-api/advanced-sms/) | | country | Provide the recipients' numbers in an international format (with prefix, e.g. `44`) or add the [country code in ISO 3166-1 alpha-2 format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `GB` = `44777777777`). See the country example request. If **`null,`** your set timezone will be used to fill the information | No | `null` | | schedule | Schedule the sending time and date in [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | No | Now | | 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 | `off` | | tag | Message label for subsequent retrieval of the user. | No | - | ### Value `number` The value number can be written as follows: - Array of phone numbers ```json [ "420777777777", "420888888888", "420999999999" ] ``` ## Channels The `channel` object decides which channels the message is sent through and in what order. **The order of the keys in your request is the order of the cascade** and SMS is not appended to it automatically - see [Channel cascade](https://www.bulkgate.com/en/docs/advanced-api/advanced-cascade/). | KEY | CHANNEL OBJECT | |:-------------|:---------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/en/docs/advanced-api/advanced-sms/) | | `viber` | [Viber – transactional](https://www.bulkgate.com/en/docs/advanced-api/advanced-viber-transactional/) | | `rcs` | [RCS](https://www.bulkgate.com/en/docs/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/en/docs/advanced-api/advanced-whatsapp/) | ## Request example ```http-json POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": ["777777777", "777777778"], "text": "example text ", "variables": {"first_name": "John"}, "country": "cz", "schedule": "2023-08-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "BulkGate", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Mr. Sender", "unicode": true } } } ``` ## Response **In case of success:** ```json { "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.](https://www.bulkgate.com/en/helpdesk/sms/message-concatenation/) **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** (description of the error) can be found in the [error types table](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/) - **code** represents http error - **detail** is an additional info about the error See all the error types for Simple API and Advanced API [here.](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/)