Specifikace 2.0

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 PARAMETRUHODNOTAPOVINNÝVÝCHOZÍ HODNOTA
application_idAplikační identifikátorAno-
application_tokenAplikační ověřovací tokenAno-
numberPole příjemců - Hodnota numberAno nebo admins nebo groups-
groupsPole čísel skupin v adresáři BulkGate. Více zdeAno nebo number nebo admins-
adminsPole čísel notifikačních administrátorů BulkGate. Více zdeAno nebo number nebo groups-
textText 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-
channelAlternativní 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 SMSNeSMS objekt
countryPoskytně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í informaceNenull
scheduleNaplánujte čas a datum odesílání v unix timestamp, nebo ISO 8601. Podívejte se na níže uvedené příkladyNeNow
duplicates_checkZvolte 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.Nenull

Hodnota number

Hodnotu number lze zapsat dvěma způsoby:

  • Pole telefonních čísel
[
    "447820125799",
    "447820100234", 
    "42060612345"
]
  • 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": "447820125799", "text": "test1 <a>", "variables": {"a": 5}},
    {"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}},
    {"number": "42060612345", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
]

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

SMS objekt

NÁZEV PARAMETRUHODNOTAPOVINNÝVÝCHOZÍ HODNOTA
textText 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_idID odesílatele, viz typ ID odesílateleNegSystem
sender_id_valueHodnota odesílatele - gOwn (např. "420 777 777 777"), gText (např. "BulkGate"), gProfile (např. "423"), gMobile or gPush (KEY)Nenull
unicodeYes/true/1 pro Unicode SMS, no/false/0 pro 7bit SMSNefalse

Typ ID odesílatele sender_id

HODNOTAVÝZNAM
gSystemSystémové číslo
gShortShort Code
gTextTextový odesílatel
gMobileMobile Connect
gPushMobile Connect push - Odešle notifikaci do vaší Mobile Connect aplikace
gOwnVlastní číslo (vyžaduje ověření čísla)
gProfileBulkGate Profil ID
<int>BulkGate Profil ID

Tabulka parametrů Viber objektu

NÁZEV PARAMETRUHODNOTAPOVINNÝVÝCHOZÍ HODNOTA
textText 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.-
senderSenderAno""
expirationČasový limit po kterém bude použit alternativní kanálNe120
buttonPovinná struktura, která ve zprávě vytvoří tlačítkoAnoObjekt tlačítka

Tabulka parametrů objektu tlačítka

NÁZEV PARAMETRUHODNOTAPOVINNÝVÝCHOZÍ HODNOTA
captionText tlačítkaAnoOK
urlURL adresaAno#

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": "447820125799", "text": "test1 <a>", "variables": {"a": 5}},
        {"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}},
        {"number": "42060612345", "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": {
        "viber": {
            "sender": "Lt. Hagan",
            "expiration": 100,
            "text": "example text"
        },
        "sms": {
            "sender_id": "gText",
            "sender_id_value": "Lt-Hagan",
            "unicode": true,
            "text": "example text"
        }
    }
}

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": [
        "447820125799",
        "447820100234", 
        "42060612345"
    ],
    "text": "Hello, <first_name> <last_name>",
    "schedule": "1526992636"
}

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

V případě úspěchu:

{
  "data": {
    "total": {
      "price": 0.0522,
      "status": {
        "sent": 0,
        "accepted": 0,
        "scheduled": 2,
        "error": 1
      }
    },
    "response": [
      {
        "status": "scheduled",
        "sms_id": "tmpde1f00539c7",
        "price": 0.0261,
        "credit": 215.81380,
        "number": "447820125799"
      },
      {
        "status": "scheduled",
        "sms_id": "tmpde1f0053f0c",
        "price": 0.0261,
        "credit": 215.81380,
        "number": "447820100234"
      },
      {
        "status": "error",
        "code": 9,
        "error": "Invalid phone number",
        "number": "42060612345"
      }
    ]
  }
}

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.

← PředchozíDalší →