Specifikace

API URL

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

https://portal.bulkgate.com/api/1.0/integration/transactional

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

Je přísně zakázáno využívat transakční SMS pro propagační/marketingové účely. Musí být použita pouze pro oznamovací účely - jako SMS oznámení.

Pokud chcete transakční routu použít k zasílání hromadných transkačních zpráv, obraťte se na naši podporu. Tuto možnost můžeme z dobrých důvodů povolit.

Pozor! Zprávu obdrží i příjemci, kteří se z odběru odhlásili (odhlášení odběru platí pouze pro promoční zprávy).

Tabulka s parametry

NÁZEV PARAMETRUHODNOTAPOVINNÝVÝCHOZÍ HODNOTA
application_idID aplikaceAno-
application_tokenOvěřovací token aplikaceAno-
tagOsobní identifikační značkaNe-
primary_channelPrimární kanál, který bude použit jako první v kaskáděNesms
phone_numberTelefonní číslo příjemnceAno-
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 unixovém čase. Podívejte se na níže uvedené příklady.Nenull
channelsAsociativní pole objektů kanálůAnoObjekt kanálu
duplicates_checkZvolte true, chcete-li zabránit odesílání duplicitních zpráv na uvedené telefonní číslo. Pokud je aktivní false, žádné duplikáty nebudou odstraněny.Nefalse

Tabulka parametrů Viber objektu

NÁZEV PARAMETRUHODNOTAPOVINNÝVÝCHOZÍ HODNOTA
senderNázev textového odesílateleNe-
expirationČas po kterém zprávě vyprší platnostAno3600
textText zprávy. 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[]

Tabulka parametrů SMS objektu

NÁZEV PARAMETRUHODNOTAPOVINNÝVÝCHOZÍ HODNOTA
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
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[]

Typ ID odesílatele sender_id

HODNOTAPOPIS
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)
gProfileID profilu odesílatele
<int>ID profilu odesílatele

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

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

{
    "application_id": "####",
    "application_token": "###########################################",
    "tag": "",
    "primary_channel": "sms",
    "phone_number": "420777777777",
    "country": "cz",
    "channels": {
        "viber": {
            "sender": "BulkGate",
            "expiration": 3600,
            "text": "test <variable_1>",
            "variables": {
                "variable_1": "name"
            }
        },
        "sms": {
            "sender_id": "gSystem",
            "sender_id_value": "BulkGate",
            "unicode": false,
            "text": "test <variable_1>",
            "variables": {
                "variable_1": "name"
            }
        }
    }
}

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

V případě úspěchu

{
    "data": {
        "status": "accepted",
        "message_id": "omni-############",
        "part_id": [
            "omni-##############"
        ],
        "number": "420777777777",
        "channel": "sms"
    }
}

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 chyby) můžete vidět v tabulce typů chyb,
  • code představuje http error
  • detail je dodatečná informace o chybě

Všechny typy chyb pro Simple API a Advanced API můžete najít zde.

Specifikace →