Hromadné transakční zprávy – specifikace

API URL

Adresa URL používaná k odesílání požadavků HTTP:

https://portal.bulkgate.com/api/1.0/integration/transactional-bulk

Poznámka

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

POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Pozor

Je přísně zakázáno využívat transakční SMS pro propagační/marketingové účely. Musí být použita pouze pro oznamovací účely - jako SMS oznámení.

Poznámka

Pokud chcete transakční routu použít k zasílání hromadných transkačních zpráv, obraťte se na naši podporu. Tuto možnost můžeme z dobrých důvodů povolit.

Upozornění

Zprávu obdrží i příjemci, kteří se z odběru odhlásili (odhlášení odběru platí pouze pro promoční zprávy).

Tabulka s parametry

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
application_id	ID aplikace	Ano	-
application_token	Ověřovací token aplikace	Ano	-
tag	Osobní identifikační značka	Ne	-
messages	Pole zpráv	Ano	Objekt zprávy

Objekt zprávy

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
primary_channel	Primární kanál, který bude použit jako první v kaskádě	Ne	`sms`
phone_number	Telefonní číslo příjemnce	Ano	-
country	Poskytněte čísla příjemců v mezinárodním formátu (s prefixem, např. `420`) nebo přidejte kód země (`775123456` + `CZ` = `420775123456`). Podívejte se na příklad požadavku země. Pokud je hodnota `null,` poté se použije vaše nastavená časová zóna pro doplnění informace	Ne	`null`
schedule	Naplánujte čas a datum odesílání v unixovém čase. Podívejte se na níže uvedené příklady.	Ne	`null`
channels	Asociativní pole objektů kanálů	Ano	Objekt kanálu

Tabulka parametrů Viber objektu

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
sender	Jméno odesilatele	Ne	-
expiration	Čas po kterém zprávě vyprší platnost	Ne	`3600`
text	Text zprávy. 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	`[]`

Tabulka parametrů SMS objektu

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
sender_id	ID odesílatele, viz typ ID odesílatele	Ne	`gSystem`
sender_id_value	Hodnota odesílatele - `gOwn` (např. "420 777 777 777"), `gText` (např. "BulkGate"), `gProfile` (např. "423"), `gMobile` or `gPush` (KEY)	Ne	`''`
unicode	`Yes`/`true`/`1` pro Unicode SMS, `no`/`false`/`0` pro 7bit SMS	Ne	`false`
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	`[]`

Typ ID odesílatele `sender_id`

HODNOTA	POPIS
`gSystem`	Systémové číslo
`gShort`	Short Code
`gText`	Textový odesílatel
`gMobile`	Mobile Connect
`gPush`	Mobile Connect push - Odešle notifikaci do vaší Mobile Connect aplikace
`gOwn`	Vlastní číslo (vyžaduje ověření čísla)
`gProfile`	ID profilu odesílatele
`<int>`	ID profilu odesílatele

Příklad úplného požadavku:

POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test <variable_1>", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777778", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test <variable_1>", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } } } } ] }

Odpověď na tento příkaz může být:

V případě úspěchu

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "message_id": "#############-0", "part_id": [ "#############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "scheduled", "message_id": "#############-1", "part_id": [ "#############-1" ], "number": "420777777778", "channel": "sms" } ] } }

V případě chyby:

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } }

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

Kde:

type a error popis chyby nalezente v tabulce typů chyb
code představuje http chyba
detail je dodatečná informace o chybě

Všechny typy chyb pro Simple API a Advanced API můžete najít zde.

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

Zeptat se AI Zkopírováno