> [!CAUTION] > It is **strictly prohibited** to exploit SMS notification for promotional/marketing uses. It must be used for notification purposes only - as a [transactional SMS.](https://www.bulkgate.com/en/helpdesk/general-information/difference-promotional-transactional-sms/) ## API URL URL used to send HTTP requests: ```url https://portal.bulkgate.com/api/1.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/1.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 ID](https://www.bulkgate.com/en/docs/api-administration-tokens/api-administration/) | **Yes** | - | | application_token | [Application token](https://www.bulkgate.com/en/docs/api-administration-tokens/api-tokens/) | **Yes** | - | | number | Recipient 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 the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), 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 | `[]` | | unicode | `Yes`/`true`/`1` for Unicode SMS, `no`/`false`/`0` for 7bit SMS | No | `false` | | sender_id | Sender ID, see [Sender ID type](#sender-id-type-sender-id) | No | `gSystem` | | sender_id_value | Sender value - `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 | `null` | | country | Provide recipient numbers in international format (with prefix, for e.g `44`), or add [country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`7820125799` + `GB` = `447820125799`). See the example of a country requirement. If the value is **`null,`** your set time zone will be used to fill in 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 mins. If **`off`** no duplicates will be removed. | No | `off` | | tag | Message label for subsequent retrieval of the user. | No | - | ### Sender ID type `sender_id` | VALUE| MEANING| |:--- |:---| |`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 the Mobile Connect app| |`gOwn` |Own number (requires number verification)| |`gProfile`|[BulkGate Profile ID](https://www.bulkgate.com/en/helpdesk/sms/sender-id-profile/)| | `` |BulkGate Profile ID| ## Request example ```http-json POST /api/1.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": "447820125799", "unicode": true, "text": "Hello, ", "variables": {"first_name": "John", "last_name": "Doe"}, "sender_id": "gText", "sender_id_value": "BulkGate", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00" } ``` ## Response **In case of success:** ```json { "data": { "status": "accepted", "sms_id": "tmpde1bcd4b1d1", "part_id": [ "tmpde1bcd4b1d1_1", "tmpde1bcd4b1d1" ], "number": "447820125799" } } ``` 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/)