Specifikace

API URL

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

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

POST /api/1.0/integration/transactional-bulk 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 PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
application_id	ID aplikace	Ano	-
application_token	Ověřovací token aplikace	Ano	-
tag	Osobní identifikační značka	Ne	-
messages	Pole zpráv	Ano	Objekt zprávy

Objekt zprávy

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
primary_channel	Primární kanál, který bude použit jako první v kaskádě	Ne	sms
phone_number	Telefonní číslo příjemnce	Ano	-
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 unixovém čase. Podívejte se na níže uvedené příklady.	Ne	null
channels	Asociativní pole objektů kanálů	Ano	Objekt kanálu

Tabulka parametrů Viber objektu

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
sender	Jméno odesilatele	Ne	-
expiration	Čas po kterém zprávě vyprší platnost	Ano	3600
text	Text zprávy. Je možné doplnit proměnné do šablony z pole variables (další parametr) Hello <first_name> <last_name> ....	Ano	-
variables	Asociativní pole pro doplnění proměnných do textu např: {"first_name": "John", "last_name": "Doe"}	Ne	[]

Tabulka parametrů SMS objektu

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
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
text	Text 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	-
variables	Asociativní pole pro doplnění proměnných do textu např: {"first_name": "John", "last_name": "Doe"}	Ne	[]

Typ ID odesílatele sender_id

HODNOTA	POPIS
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	ID profilu odesílatele
<int>	ID profilu odesílatele

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

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

{
  "application_id": "####",
  "application_token": "######################################",
  "tag": "",
  "messages": [
    {
      "primary_channel": "sms",
      "phone_number": "420777777777",
      "country": "cz",
      "schedule": 1683101313,
      "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"
          }
        }
      }
    },
    {
      "primary_channel": "sms",
      "phone_number": "420777777778",
      "country": "cz",
      "schedule": 1683101313,
      "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": {
        "total": {
            "status": {
                "sent": 0,
                "accepted": 0,
                "scheduled": 2,
                "error": 0,
                "blacklisted": 0,
                "invalid_number": 0,
                "invalid_sender": 0
            }
        },
        "response": [
            {
                "status": "scheduled",
                "message_id": "#############-0",
                "part_id": [
                    "#############-0"
                ],
                "number": "420777777777",
                "channel": "sms"
            },
            {
                "status": "scheduled",
                "message_id": "#############-1",
                "part_id": [
                    "#############-1"
                ],
                "number": "420777777778",
                "channel": "sms"
            }
        ]
    }
}

V případě chyby:

{
    "data": {
        "total": {
            "status": {
                "sent": 0,
                "accepted": 0,
                "scheduled": 0,
                "error": 0,
                "blacklisted": 0,
                "invalid_number": 0,
                "invalid_sender": 0
            }
        },
        "response": []
    }
}

{
    "type": "unknown_identity",
    "code": 401,
    "error": "Unknown identity / unauthorized / empty application_id",
    "detail": null
}

Kde:

• type a error popis chyby nalezente v tabulce typů chyb,
• code představuje http chyba
• detail je dodatečná informace o chybě

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