Specifikace v2

API URL

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

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

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

Dokumentaci předchozí verze lze nalézt zde.

Je přísně zakázáno zneužívat transakční SMS pro promoční/marketingové účely. Může být použiván pouze pro notifikační účely - jako SMS notifikace.

Pokud byste chtěli použít transakční routu pro zaslání hromadné notifikační zprávy, obraťe se prosím na naši popdporu. Na základě oprávněného důvodu vám můžeme tuto možnost povolit.

Tabulka s parametry

NÁZEV PARAMETRUHODNOTAPOVINNÝVÝCHOZÍ HODNOTA
application_idAplikační identifikátorAno-
application_tokenAplikační ověřovací tokenAno-
numberČíslo příjemce nebo pole čísel příjemců - Hodnota numberAno nebo admins nebo groups-
adminČíslo notifikačního admina BulkGate. Více zdeAno nebo number-
textText SMS zprávy (max. 612 znaků nebo 268 znaků, jestliže je aktivován Unicode), UTF-8 kódování. Je možné doplnit proměnné do šablony z pole variables (další parametr) Hello <first_name> <last_name> ....Ano-
variablesAsociativní pole pro doplnění proměnných do textu např: {"first_name": "John", "last_name": "Doe"}Ne[]
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ě ve formátu ISO 3166-1 alpha-2 (775123456 + CZ = 420775123456). Podívejte se na příklad požadavku země. Pokud je hodnota null, je použita země z vašeho uživatelského profilu.Nenull
scheduleNaplánujte čas a datum odesílání v unix timestamp, nebo ISO 8601.NeNow
duplicates_checkZvolte možnost on, chcete-li zabránit odesílání duplicitních zpráv na stejné telefonní číslo. Zprávy se stejným textem zaslaným na stejné číslo budou odstraněny, pokud je časový interval kratší než 5 minut. Pokud je aktivní možnost off, žádné duplikáty nebudou odstraněny.Neoff

Hodnota number

Hodnotu number lze zapsat následujícím způsobem:

  • Pole telefonních čísel
[
    "447820125799",
    "447820100234", 
    "42060612345"
]

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í. Je možné doplnit proměnné do šablony z pole variables (další parametr) Hello <first_name> <last_name> ....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

VALUEDESCRIPTION
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 s parametry 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í. Je možné doplnit proměnné do šablony z pole variables (další parametr) Hello <first_name> <last_name> ....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.-
senderTextový odesilatelAno""
expirationČasový limit po jejimž vypršení bude použit alternativní kanálNe120

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

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

{
    "application_id": "********",
    "application_token": "**************",
    "number": ["777777777", "777777778"], 
    "text": "example text <first_name>",
    "variables": {"first_name": "John"},
    "country": "cz",
    "schedule": "2023-08-14T18:30:00-01:00",
    "channel": {
      "viber": {
        "sender": "BulkGate",
        "expiration": 100
      },
      "sms": {
        "sender_id": "gText",
        "sender_id_value": "Mr. Sender",
        "unicode": true
      }
    }
}

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": 0,
                "invalid_sender": 0,
                "duplicity_message": 0
            }
        },
        "response": [
            {
                "status": "scheduled",
                "message_id": "transactional-64afe5f28ffc2-0",
                "part_id": [
                    "transactional-64afe5f28ffc2-0"
                ],
                "number": "420777777777",
                "channel": "viber"
            },
            {
                "status": "scheduled",
                "message_id": "transactional-64afe5f28ffc2-1",
                "part_id": [
                    "transactional-64afe5f28ffc2-1"
                ],
                "number": "420777777778",
                "channel": "viber"
            }
        ]
    }
}

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

Specifikace v1 →