Specifikace v2
API URL
Adresa URL používaná k odeslání požadavků HTTP:
https://portal.bulkgate.com/api/2.0/advanced/promotional
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
Dokumentaci předchozí verze naleznete zde.
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 | Pole příjemců - Hodnota number | Ano nebo admins nebo groups | - |
groups | Pole čísel skupin v adresáři BulkGate. Více zde | Ano nebo number nebo admins | - |
admins | Pole čísel notifikačních administrátorů BulkGate. Více zde | Ano nebo number nebo groups | - |
text | Text SMS zprávy (max. 612 znaků nebo 268 znaků, jestliže je aktivován Unicode), UTF-8 kódování. | Ano, pokud je number zadán polem čísel nebo je použit parametr groups nebo admin | - |
channel | Alternativní kanály. Kanály jsou seřazeny v kaskádě, pokud nebude možné doručit vaši zprávu skrze kanál s nejvyšší prioritou, bude použit kanál s nižší prioritou. Pokud nebude možné doručit zprávu skrze ani jeden kanál v seznamu, zpráva bude zaslána 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ě (777777777 + CZ = 420777777777 ). 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 unix timestamp, nebo ISO 8601. Podívejte se na níže uvedené příklady. | Ne | Now |
duplicates_check | Zvolte možnost same_text , chcete-li zabránit odesílání duplicitních zpráv na stejné telefonní číslo. Zakažte možnost odeslat zprávu se stejným nebo jiným textem na stejné číslo s možností same_number . Pokud je aktivní null , žádné duplikáty nebudou odstraněny. | Ne | null |
number
Hodnota Hodnotu number lze zapsat dvěma způsoby:
- Pole telefonních čísel
[
"420777777777",
"420888888888",
"420999999999"
]
- Asociativní pole se schématem
number
,text
avariables
, kde jediný povinný parametr jenumber
. Pokudnumber
není vyplněn, zpráva se přeskočí.
[
{"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 šablony parametru text
je možné doplnit proměnné z pole variables
.
Tabulka kanálů
Tabulka všech podporovaných alternativních kanálů
KANÁL | ODKAZ |
---|---|
sms | SMS objekt |
viber | Viber objekt |
rcs | RCS objekt |
whatsapp | WhatsApp objekt |
Tabulka parametrů SMS objektu
NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA |
---|---|---|---|
text | Text SMS zprávy (max. 612 znaků nebo 268 znaků, jestliže je aktivován Unicode), UTF-8 kódování. | Ano, pokud není použit obecný parametr text . Pokud SMS objekt obsahuje text parametr společně s obecným parametrem text , bude použit specifičtější SMS text . | - |
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 | null |
unicode | Yes /true /1 pro Unicode SMS, no/false/0 pro 7bit SMS | Ne | false |
sender_id
Typ ID odesílatele HODNOTA | VÝZNAM |
---|---|
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 | BulkGate Profil ID |
<int> | BulkGate Profil ID |
Tabulka parametrů Viber objektu
NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA |
---|---|---|---|
text | Text SMS zprávy (max. 612 znaků nebo 268 znaků, jestliže je aktivován Unicode), UTF-8 kódování. | Ano, pokud není použit obecný parametr text . Pokud Viber objekt obsahuje text parametr společně s obecným parametrem text , bude použit specifičtější Viber text . | - |
sender | Sender | Ano | - |
expiration | Časový limit po kterém bude použit alternativní kanál. | Ne | 120 |
button | Povinná struktura, která ve zprávě vytvoří tlačítko. | Ano | Objekt tlačítka |
image | URL adresa obrázku, který se zobrazí ve zprávě. | Ne | null |
Tabulka parametrů objektu tlačítka
NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA |
---|---|---|---|
caption | Text tlačítka | Ano | OK |
url | URL adresa | Ano | # |
Příklad úplného požadavku:
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
{
"application_id": "APPLICATION_ID",
"application_token": "APPLICATION_TOKEN",
"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": "Jít na BulkGate",
"url": "https://www.bulkgate.com/cs/blog/rcs-budoucnost-mobilnich-zprav-pro-firmy/"
},
"image": "https://www.bulkgate.com/wp-content/uploads/2023/06/rcs-rich-communication-services.jpg",
"text": "RCS: Budoucnost mobilních zpráv pro firmy*\n\nPřáli jste si někdy, abyste mohli v SMS zprávě poslat víc než jen text, například obrázek ve vysokém rozlišení nebo interaktivní tlačítko? Nebo jste si přáli obdržet potvrzení o přečtení, abyste si ověřili, že byla vaše zpráva úspěšně doručena? Služba Rich Communication Services (RCS) je tu, aby revolučním způsobem změnila způsob obchodní komunikace, zlepšila zážitek ze zasílání zpráv a překonala tato omezení."
},
"sms": {
"sender_id": "gText",
"sender_id_value": "Lt-Hagan",
"unicode": true,
"text": "RCS: Budoucnost mobilních zpráv pro firmy"
}
}
}
Příklad požadavku zadání příjemců polem čísel a naplánování čas v unix timestamp:
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache
{
"application_id": "APPLICATION_ID",
"application_token": "APPLICATION_TOKEN",
"number": [
"420777777777",
"420888888888",
"420999999999"
],
"text": "Hello, <first_name> <last_name>",
"schedule": "1526992636"
}
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": 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 čá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.