## API URL
Adresa URL používaná na odosielanie HTTP požiadaviek:
```url
https://portal.bulkgate.com/api/2.0/advanced/promotional
```
> [!NOTE]
> Ak sa požiadavka nedostane k cieľu, zopakujte ju na [záložnom serveri](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/zalozny-server/) `backup1.bulkgate.com`.
## Podporované HTTP metódy
- `POST` - `application/json`
```http
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```
## Tabuľka s parametrami
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------:|:-------------------------:|
| application_id | [Aplikačný identifikátor](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/administracia-api/) | **Áno** | - |
| application_token | [Aplikačný overovací token](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/api-tokeny/) | **Áno** | - |
| number | Pole príjemcov - [Hodnota number](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-promotional/2.0/) | **Áno** alebo `admins` alebo `groups` | - |
| groups | Pole čísel skupín v adresári BulkGate. [Viac tu](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-promotional-posielanie-sprav-skupinam-z-adresara/) | **Áno** alebo `number` alebo `admins` | - |
| admins | Pole čísel notifikačných administrátorov BulkGate. [Viac tu](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-promotional-posielanie-propagacnych-sprav-administratorom/) | **Áno** alebo `number` alebo `groups` | - |
| text | Text SMS správy (max. 612 znakov alebo 268 znakov, ak je aktivovaný Unicode), kódovanie UTF-8. | **Áno**, ak je `number` zadaný poľom čísel alebo je použitý parameter `groups` alebo `admin` | - |
| channel | Alternatívne kanály. Kanály sa skúšajú v kaskáde v poradí, v akom ich v objekte uvediete - ak nebude možné doručiť správu prvým kanálom, použije sa ďalší v poradí. SMS sa na koniec kaskády automaticky **nepridáva**; ak ju chcete ako poslednú záchranu, uveďte v kaskáde objekt `sms`. Keď nie je zadaný žiadny kanál, správa sa odošle ako SMS. | Nie | [SMS objekt](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-sms/) |
| country | Uveďte čísla príjemcov v medzinárodnom formáte (s predvoľbou, napr. `420`) alebo pridajte [kód krajiny](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Pozrite si príklad požiadavky s krajinou. Ak je hodnota **`null`**, na doplnenie informácie sa použije vaše nastavené časové pásmo. | Nie | `null` |
| schedule | Naplánujte čas a dátum odoslania v [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) alebo [ISO 8601.](https://en.wikipedia.org/wiki/ISO_8601) Pozrite si príklady uvedené nižšie. | Nie | Teraz |
| duplicates_check | Zvoľte možnosť **`same_text`**, ak chcete zabrániť odosielaniu duplicitných správ na rovnaké telefónne číslo. Možnosťou **`same_number`** zakážete odoslanie správy s rovnakým alebo iným textom na rovnaké číslo. Ak je aktívna hodnota **`null`**, žiadne duplicity sa neodstránia. Duplicity sa odstraňujú **len v rámci jednej dávky**, nie naprieč požiadavkami. | Nie | `null` |
| tag | Označenie správ na ich neskoršie dohľadanie používateľom. | Nie | - |
### Hodnota `number`
Hodnotu number je možné zapísať dvoma spôsobmi:
- Pole telefónnych čísel
```json
[
"420777777777",
"420888888888",
"420999999999"
]
```
- Asociatívne pole so schémou `number`, `text` a `variables`, kde jediný povinný parameter je `number`. Ak `number` nie je vyplnený, správa sa preskočí.
```json
[
{"number": "420777777777", "text": "test1 ", "variables": {"a": 5}},
{"number": "420888888888", "text": "test2 ", "variables": {"b": 5}},
{"number": "420999999999", "text": "test3 ", "variables": {"c": 3, "d": "abc"}}
]
```
Do šablóny parametra `text` je možné doplniť premenné z poľa `variables`.
## Kanály
Objekt `channel` určuje, ktorými kanálmi sa správa odošle a v akom poradí. **Poradie kľúčov v požiadavke je poradím kaskády** a SMS sa do nej automaticky nepridáva - pozri [Kaskáda kanálov](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-kaskada/).
| KĽÚČ | OBJEKT KANÁLA |
|:-------------|:-----------------------------------------------------------------|
| `sms` | [SMS](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-sms/) |
| `viber` | [Viber – propagačný](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-viber-promo/) |
| `rcs` | [RCS](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-rcs/) |
| `whatsapp` | [WhatsApp](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-whatsapp/) |
## Príklady požiadaviek
**Príklad úplnej požiadavky:**
```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": "Hello, ",
"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": "Prejsť na BulkGate",
"url": "https://www.bulkgate.com/cs/blog/rcs-budoucnost-mobilnich-zprav-pro-firmy/"
},
"image": "https://www.bulkgate.com/assets/illustrations/rcs-rich-communication-services.jpg",
"text": "*RCS: Budúcnosť mobilných správ pre firmy*\n\nŽelali ste si niekedy, aby ste mohli v SMS správe poslať viac než len text, napríklad obrázok vo vysokom rozlíšení alebo interaktívne tlačidlo? Alebo ste si želali dostať potvrdenie o prečítaní, aby ste si overili, že vaša správa bola úspešne doručená? Služba Rich Communication Services (RCS) je tu, aby revolučným spôsobom zmenila spôsob obchodnej komunikácie, zlepšila zážitok z posielania správ a prekonala tieto obmedzenia."
},
"sms": {
"sender_id": "gText",
"sender_id_value": "Lt-Hagan",
"unicode": true,
"text": "RCS: Budúcnosť mobilných správ pre firmy"
}
}
}
```
**Príklad požiadavky so zadaním príjemcov poľom čísel a naplánovaním času v 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"
}
```
## Odpoveď
**V prípade úspechu:**
```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"
}
]
}
}
```
Kde:
- **part_ID** je pole ID častí pôvodnej dlhej správy, ktorá bola rozdelená, pretože nespĺňala limit 160 znakov pre jednu správu. Viac [tu](https://www.bulkgate.com/sk/centrum-pomoci/sms/zretazenie-sprav/).
**V prípade chyby:**
```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
}
```
Kde:
- **type** a **error** (popis chyby) nájdete v [tabuľke typov chýb](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/)
- **code** predstavuje HTTP chybu
- **detail** je doplňujúca informácia o chybe
Všetky typy chýb pre Simple API a Advanced API nájdete [tu](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/).