Specifikace v1

API URL

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

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

POST /api/1.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

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	-
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
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 unix timestamp, nebo ISO 8601. Podívejte se na níže uvedené příklady	Ne	Nyní
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	Označení zpráv pro následné dohledání uživatele	Ne	-

Hodnota number

Hodnotu number lze zapsat dvěma způsoby:

• Pole telefonních čísel

[
    "420775123456",
    "420606123456", 
    "44771447678"
]

• 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": "420775123456", "text": "test1 <a>", "variables": {"a": 5}},
    {"number": "420606123456", "text": "test2 <a>", "variables": {"b": 5}},
    {"number": "44771447678", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
]

Do šablony parametru text je možné doplnit proměnné z pole variables.

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

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

POST /api/1.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": "420775123456", "text": "test1 <a>", "variables": {"a": 5}},
        {"number": "420606123456", "text": "test2 <a>", "variables": {"b": 5}},
        {"number": "44771447678", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
    ],
    "unicode": true,
    "groups": [1, 2],
    "admins": [1, 4],
    "text": "Hello, <first_name> <last_name>",
    "sender_id": "gText",
    "sender_id_value": "BulkGate",
    "country": "cz",
    "schedule": "2018-05-14T18:30:00-01:00"
}

Příklad požadavku zadání příjemců polem čísel a naplánování čas v unix timestamp:

POST /api/1.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": [
        "420775123456",
        "420606123456", 
        "44771447678"
    ],
    "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": "420775123456",
        "channel": "sms"
      },
      {
        "status": "scheduled",
        "sms_id": "idyrcmdd-1",
        "part_id": [
                    "idyrcmdd-1_1",
                    "idyrcmdd-1"
                ],
        "number": "420606123456",
        "channel": "sms"
      },
      {
        "status": "invalid_number",
        "code": 400,
        "error": "Invalid phone number",
        "detail": null,
        "number": "44771447678",
        "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 info zde.

V případě chyby:

{
    "type": "invalid_phone_number",
    "code": 400,
    "error": "Neplatné číslo",
    "detail": null
}

{
    "type": "unknown_identity",
    "code": 401,
    "error": "Neznámá identita / neautorizovaná / prázdná 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.