Transakční SMS – specifikace (Advanced API)

Pozor

Je přísně zakázáno zneužívat transakční SMS pro promoční/marketingové účely. Může být použiván pouze pro notifikační účely - jako SMS notifikace.

Poznámka

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. 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:

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

Poznámka

Nedostane-li se požadavek k cíli, zopakujte ho na záložním serveru backup1.bulkgate.com.

Podporované HTTP metody

POST - application/json

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	Ano	-
application_token	Aplikační ověřovací token	Ano	-
number	Číslo příjemce nebo pole čísel příjemců - Hodnota number	Ano nebo `admin`	-
admin	Číslo notifikačního admina BulkGate. Více zde	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 <first_name> <last_name> ....`	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
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 (`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, nebo 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

[ "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ů.

KLÍČ	OBJEKT KANÁLU
`sms`	SMS
`viber`	Viber – transakční
`rcs`	RCS
`whatsapp`	WhatsApp

Příklad požadavku

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 } } }

Odpověď

V případě úspěchu:

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

V případě 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 (popisek erroru) můžete vidět v tabulce typů errorů
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.

Byla tato stránka užitečná?

Zeptat se AI Zkopírováno