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

API URL

Adresa URL používaná na odosielanie HTTP požiadaviek:

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

Poznámka

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

Podporované HTTP metódy

POST - application/json

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	Áno	-
application_token	Aplikačný overovací token	Áno	-
number	Pole príjemcov - Hodnota number	Áno alebo `admins` alebo `groups`	-
groups	Pole čísel skupín v adresári BulkGate. Viac tu	Áno alebo `number` alebo `admins`	-
admins	Pole čísel notifikačných administrátorov BulkGate. Viac tu	Á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
country	Uveďte čísla príjemcov v medzinárodnom formáte (s predvoľbou, napr. `420`) alebo pridajte kód krajiny (`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, alebo 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

[ "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čí.

[ {"number": "420777777777", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 <b> <d>", "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.

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

Príklady požiadaviek

Príklad úplnej požiadavky:

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 <a>", "variables": {"a": 5}}, {"number": "420888888888", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420999999999", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ], "groups": [1, 2], "admins": [1, 4], "text": "Hello, <first_name> <last_name>", "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:

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, <first_name> <last_name>", "schedule": "1526992636" }

Odpoveď

V prípade úspechu:

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

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é