> [!CAUTION] > Je ***přísně zakázáno*** zneužívat [transakční SMS](https://www.bulkgate.com/cs/centrum-napovedy/obecne-informace/rozdil-propagacni-transakcni-sms/) pro promoční/marketingové účely. Může být použiván pouze pro notifikační účely - jako SMS notifikace. > [!NOTE] > Pokud byste chtěli použít transakční routu pro zaslání hromadné notifikační zprávy, obraťte se prosím na [naši podporu.](https://www.bulkgate.com/cs/kontakt/) Na základě oprávněného důvodu vám můžeme tuto možnost povolit. ## API URL Adresa URL používaná k odeslání požadavků HTTP: ```url https://portal.bulkgate.com/api/2.0/advanced/transactional ``` > [!NOTE] > Nedostane-li se požadavek k cíli, zopakujte ho na [záložním serveru](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/zalozni-server/) `backup1.bulkgate.com`. ## Podporované HTTP metody - `POST` - `application/json` ```http POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Tabulka s parametry | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------:|:-------------------------:| | application_id | [Aplikační identifikátor](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/administrace-api/) | **Ano** | - | | application_token | [Aplikační ověřovací token](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/api-tokeny/) | **Ano** | - | | number | Číslo příjemce nebo pole čísel příjemců - [Hodnota number](#hodnota-number) | **Ano** nebo `admin` | - | | admin | Číslo notifikačního admina BulkGate. [Více zde](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-transactional-posilani-notifikacnich-zprav-administratorum/) | **Ano** nebo `number` | - | | text | Text SMS zprávy (max. 612 znaků nebo 268 znaků, jestliže je aktivován Unicode), UTF-8 kódování. Je možné doplnit proměnné do šablony z pole `variables` (další parametr) `Hello ....` | **Ano** | - | | variables | Asociativní pole pro doplnění proměnných do textu např: `{"first_name": "John", "last_name": "Doe"}` | Ne | `[]` | | channel | Alternativní kanály. Kanály se zkoušejí v kaskádě v pořadí, v jakém je v objektu uvedete - pokud nebude možné doručit zprávu prvním kanálem, použije se další v pořadí. SMS se na konec kaskády **nepřidává** automaticky; pokud ji chcete jako poslední záchranu, uveďte v kaskádě objekt `sms`. Když není zadaný žádný kanál, odešle se zpráva jako SMS. | Ne | [SMS objekt](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-sms/) | | country | Poskytněte čísla příjemců v mezinárodním formátu (s prefixem, např. `420`), nebo přidejte [kód země ve formátu ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420777777777`). Podívejte se na příklad požadavku země. Pokud je hodnota **`null`**, je použita země z vašeho uživatelského profilu. | Ne | `null` | | schedule | Naplánujte čas a datum odesílání v [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) nebo [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | Ne | Now | | duplicates_check | Zvolte možnost **`on`**, chcete-li zabránit odesílání duplicitních zpráv na stejné telefonní číslo. Zprávy se stejným textem zaslaným na stejné číslo budou odstraněny, pokud je časový interval kratší než 5 minut. Pokud je aktivní možnost **`off`**, žádné duplikáty nebudou odstraněny. | Ne | `off` | | tag | Označení zpráv pro následné dohledání uživatele. | Ne | - | ### Hodnota `number` Hodnotu `number` lze zapsat následujícím způsobem: - Pole telefonních čísel ```json [ "420777777777", "420888888888", "420999999999" ] ``` ## Kanály Objekt `channel` určuje, kterými kanály se zpráva odešle a v jakém pořadí. **Pořadí klíčů v requestu je pořadím kaskády** a SMS se do ní nepřidává automaticky - viz [Kaskáda kanálů](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-kaskada/). | KLÍČ | OBJEKT KANÁLU | |:-------------|:-----------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-sms/) | | `viber` | [Viber – transakční](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-viber-transakcni/) | | `rcs` | [RCS](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-whatsapp/) | ## Příklad požadavku ```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 } } } ``` ## Odpověď **V případě úspěchu:** ```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" } ] } } ``` Kde: - **part_ID** je pole ID částí původní dlouhé zprávy, která byla rozdělena, protože nesplňovala limit 160 znaků pro jednu zprávu. Více [zde.](https://www.bulkgate.com/cs/centrum-napovedy/sms/zretezeni-zprav/) **V případě 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** (popisek erroru) můžete vidět v [tabulce typů errorů](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/) - **code** představuje http error - **detail** je dodatečná informace o erroru Všechny typy errorů pro Simple API a Advanced API můžete najít [zde.](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/)