Transakčné SMS – špecifikácia (Advanced API)

Pozor

Je prísne zakázané zneužívať transakčné SMS na propagačné/marketingové účely. Smú sa používať len na notifikačné účely – ako SMS notifikácie.

Poznámka

Ak by ste chceli použiť transakčnú routu na odoslanie hromadnej notifikačnej správy, obráťte sa, prosím, na našu podporu. Na základe oprávneného dôvodu vám túto možnosť môžeme povoliť.

API URL

Adresa URL, na ktorú sa posielajú požiadavky HTTP:

https://portal.bulkgate.com/api/2.0/advanced/transactional

Poznámka

Ak sa požiadavka nedostane do cieľa, zopakujte ju na záložnom serveri backup1.bulkgate.com.

Podporované HTTP metódy

POST - application/json

POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Tabuľka s parametrami

NÁZOV PARAMETRA	HODNOTA	POVINNÝ	PREDVOLENÁ HODNOTA
application_id	Identifikátor aplikácie	Áno	-
application_token	Overovací token aplikácie	Áno	-
number	Číslo príjemcu alebo pole čísel príjemcov – Hodnota number	Áno alebo `admin`	-
admin	Číslo notifikačného admina BulkGate. Viac tu	Áno alebo `number`	-
text	Text SMS správy (max. 612 znakov alebo 268 znakov, ak je aktivovaný Unicode), kódovanie UTF-8. Do šablóny je možné doplniť premenné z poľa `variables` (ďalší parameter) `Hello <first_name> <last_name> ....`	Áno	-
variables	Asociatívne pole na doplnenie premenných do textu, napr.: `{"first_name": "John", "last_name": "Doe"}`	Nie	`[]`
channel	Alternatívne kanály. Kanály sa skúšajú v kaskáde v poradí, v akom ich v objekte uvediete – ak sa správu nepodarí doručiť prvým kanálom, použije sa ďalší v poradí. SMS sa na koniec kaskády nepridáva automaticky; 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
country	Zadajte čísla príjemcov v medzinárodnom formáte (s predvoľbou, napr. `420`) alebo pridajte kód krajiny vo formáte ISO 3166-1 alpha-2 (`775123456` + `CZ` = `420777777777`). Pozrite si príklad požiadavky s krajinou. Ak je hodnota `null`, použije sa krajina z vášho používateľského profilu.	Nie	`null`
schedule	Naplánujte čas a dátum odoslania v unix timestamp, alebo ISO 8601.	Nie	Teraz
duplicates_check	Zvoľte možnosť `on`, ak chcete zabrániť odosielaniu duplicitných správ na rovnaké telefónne číslo. Správy s rovnakým textom odoslané na rovnaké číslo sa odstránia, ak je časový odstup kratší ako 5 minút. Ak je aktívna možnosť `off`, žiadne duplicity sa neodstránia.	Nie	`off`
tag	Označenie správ na ich neskoršie dohľadanie používateľom.	Nie	-

Hodnota `number`

Hodnotu number je možné zapísať takto:

Pole telefónnych čísel

[ "420777777777", "420888888888", "420999999999" ]

Kanály

Objekt channel určuje, ktorými kanálmi sa správa odošle a v akom poradí. Poradie kľúčov v requeste je poradím kaskády a SMS sa do nej nepridáva automaticky – pozrite Kaskáda kanálov.

KĽÚČ	OBJEKT KANÁLA
`sms`	SMS
`viber`	Viber – transakčný
`rcs`	RCS
`whatsapp`	WhatsApp

Príklad požiadavky

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 <first_name>", "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 } } }

Odpoveď

V prípade úspechu:

{ "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 častí pôvodnej dlhej správy, ktorá bola rozdelená, pretože prekročila limit 160 znakov pre jednu správu. Viac tu.

V prípade chyby:

{ "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null }

{ "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
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.

Bola táto stránka užitočná?

Opýtať sa AI Skopírované