Specifikace v2 · BulkGate Helpdesk

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ťte se prosím na naši podporu. Na základě oprávněného důvodu vám můžeme tuto možnost povolit.

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	Číslo příjemce nebo pole čísel příjemců - Hodnota number	Ano nebo `admins` nebo `groups`	-
admin	Číslo notifikačního admina BulkGate. Více zde	Ano nebo `number`	-
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	`[]`
channel	Alternativní 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 SMS.	Ne	SMS objekt
country	Poskytně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` = `420777777777`). Podívejte se na příklad požadavku země. Pokud je hodnota `null`, je použita země z vašeho uživatelského profilu.	Ne	`null`
schedule	Naplánujte čas a datum odesílání v unix timestamp, nebo ISO 8601.	Ne	Now
duplicates_check	Zvolte 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.	Ne	`off`

Hodnota `number`

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

Pole telefonních čísel

[
    "420777777777",
    "420888888888", 
    "420999999999"
]

Tabulka kanálů

Tabulka všech podporovaných alternativních kanálů

KANÁL	ODKAZ
`sms`	SMS objekt
`viber`	Viber objekt
`rcs`	RCS objekt
`whatsapp`	WhatsApp objekt

SMS objekt

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
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, 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_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`

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`	BulkGate Profil ID
`<int>`	BulkGate Profil ID

Viber objekt

NÁZEV PARAMETRU	HODNOTA	POVINNÝ	VÝCHOZÍ HODNOTA
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, 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`.	-
sender	Textový odesílatel	Ano	`""`
expiration	Časový limit po jehož vypršení bude použit alternativní kanál	Ne	`120`

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": {
        "whatsapp": {
            "sender": "420888888888",
            "expiration": 300,
            "message": {
                "text": "text"
            }
        },
        "rcs": {
            "sender": "BulkGate",
            "expiration": 300,
            "message": {
                "text": "text"
            }
        },
        "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 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
}