## API URL
URL used to send HTTP requests:
```url
https://portal.bulkgate.com/api/2.0/advanced/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`.
## Supported HTTP methods
- `POST` - `application/json`
```http
POST /api/2.0/advanced/promotional 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 | Array of recipients - [Value number](#value-number) | **Yes** or `admins` or `groups` | - |
| groups | Array of numbers of groups in BulkGate address book. [More info](https://www.bulkgate.com/en/docs/advanced-api/advanced-promotional-groups/) | **Yes** or `number` or `admins` | - |
| admins | Array of numbers of BulkGate administrators receiving notifications. [More info](https://www.bulkgate.com/en/docs/advanced-api/advanced-promotional-admins/) | **Yes** or `number` or `groups` | - |
| text | Text of the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), UTF-8 encoding | **Yes**, if `number` is given by the array of numbers or the parameter `groups` or `admin` is used | - |
| 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 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) (`777777777` + `GB` = `44777777777`). 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) See examples below | No | Now |
| duplicates_check | Select **`same_text`** to prevent sending duplicate messages to the same phone number. Disable the possibility to send a message with either the same or different text to the same number with **`same_number`**. If **`null`** no duplicates will be removed. Duplicates are removed **within a single batch only**, not across requests. | No | `null` |
| tag | Message label for subsequent retrieval of the user. | No | - |
### Value `number`
The value number can be written in two ways:
- Array of phone numbers
```json
[
"420777777777",
"420888888888",
"420999999999"
]
```
- Associative array with diagram `number`,` text`, and `variables`, where the only required parameter is `number`. If `number` is not filled in, the message skips.
```json
[
{"number": "420777777777", "text": "test1 ", "variables": {"a": 5}},
{"number": "420888888888", "text": "test2 ", "variables": {"b": 5}},
{"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
]
```
You can add variables from the array `variables` into the template of parameter `text`.
## 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 – promotional](https://www.bulkgate.com/en/docs/advanced-api/advanced-viber-promotional/) |
| `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 examples
**Example of full request:**
```http-json
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
{"number": "420777777777", "text": "test1 ", "variables": {"a": 5}},
{"number": "420888888888", "text": "test2 ", "variables": {"b": 5}},
{"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
],
"groups": [1, 2],
"admins": [1, 4],
"text": "RCS: The future of mobile messaging for businesses",
"country": "cz",
"schedule": "2018-05-14T18:30:00-01:00",
"channel": {
"whatsapp": {
"sender": "420777777777",
"expiration": 300,
"message": {
"text": "text"
}
},
"rcs": {
"sender": "BulkGate",
"expiration": 300,
"message": {
"text": "text"
}
},
"viber": {
"sender": "Lt. Hagan",
"expiration": 100,
"button": {
"caption": "Go To BulkGate",
"url": "https://www.bulkgate.com/en/blog/rcs-the-future-of-mobile-messaging-for-businesses/"
},
"image": "https://www.bulkgate.com/assets/illustrations/rcs-rich-communication-services.jpg",
"text": "*RCS: The future of mobile messaging for businesses*\n\nEver found yourself wishing you could send more than just text in an SMS, like a high-resolution image or an interactive button? Or perhaps you wished for a read receipt just to confirm your message got through? Rich Communication Services (RCS) is here to revolutionize the way businesses communicate, enhancing your messaging experience and overcoming these limitations."
},
"sms": {
"sender_id": "gText",
"sender_id_value": "Lt-Hagan",
"unicode": true,
"text": "RCS: The future of mobile messaging for businesses"
}
}
}
```
**Example of a request to enter recipients by the array of numbers and to schedule the time in the unix timestamp:**
```http-json
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
{
"application_id": 451,
"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
"number": [
"420777777777",
"420888888888",
"420999999999"
],
"text": "Hello, ",
"schedule": "1526992636"
}
```
## Response
**In case of success:**
```json
{
"data":{
"total":{
"status":{
"sent":0,
"accepted":0,
"scheduled":2,
"error":0,
"blacklisted":0,
"invalid_number":1,
"invalid_sender":0
}
},
"response":[
{
"status":"scheduled",
"sms_id":"idyrcmdd-0",
"part_id":[
"idyrcmdd-0_1",
"idyrcmdd-0"
],
"number":"420777777777",
"channel":"sms"
},
{
"status":"scheduled",
"sms_id":"idyrcmdd-1",
"part_id":[
"idyrcmdd-1_1",
"idyrcmdd-1"
],
"number":"420888888888",
"channel":"sms"
},
{
"status":"invalid_number",
"code":400,
"error":"Invalid phone number",
"detail":null,
"number":"420999999999",
"channel":"sms"
}
]
}
}
```
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/)