Specifikace v2 · BulkGate Helpdesk

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`
tag	Značka zprávy pro následné vyhledání uživatelem	Ne	-

Hodnota `number`

Hodnotu number lze zapsat dvěma způsoby:

Pole telefonních čísel

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

Asociativní pole se schématem number, text a variables, kde jediný povinný parametr je number. Pokud number 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`

Typ ID odesílatele `sender_id`

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
}