Webhooks

SmsManager posílá webhook události na váš server jako HTTP POST požadavky, kdykoliv se stav zprávy změní nebo přijde příchozí zpráva. Cílovou URL nakonfigurujete buď na zprávu (přes pole callback) nebo na úrovni účtu s výchozí callback URL. Události jsou doručovány jako JSON pole — SmsManager může více událostí spojit do jednoho POST — takže váš handler musí vždy iterovat přes pole, i když očekáváte pouze jednu událost. Vždy vraťte HTTP 200 pro potvrzení přijetí; pokud je váš server nedostupný, SmsManager může doručení opakovat.

Webhook payloady jsou vždy pole. I doručení jedné události je zabaleno v [...]. Ujistěte se, že váš handler prochází každou položku v poli.

Souhrn webhook událostí

Název události	Trigger	Popis
`sentMessage`	Stav odchozí zprávy se mění	Potvrzení doručení pro SMS, Viber a WhatsApp. Obvykle nejprve obdržíte stav `sent` a následně finální stav jako `delivered` nebo `undelivered`.
`incomingReplyMessage`	Příjemce odpoví na jednu z vašich zpráv	Odpověď je propojena s vaší původní zprávou přes `request_id`, `message_id` a `payload`.
`incomingMessage`	Dorazí nevyžádaná příchozí zpráva	Nová zpráva přijatá na jednom z vašich čísel, která není spojena s žádnou odchozí zprávou.

Událost sentMessage

SmsManager posílá událost sentMessage při každé změně stavu odchozí zprávy. Obvykle obdržíte počáteční událost sent nebo sending krátce po API volání a následně finální událost stavu doručení.

Reference polí

string

Jedinečný identifikátor původního API požadavku, který tuto zprávu odeslal.Příklad: "bc36f3d1-d284-463a-921b-a3560c154649"

string

Jedinečný identifikátor této zprávy. Když byla zpráva odeslána přes POST /messages, toto ID má tvar <base_id>-<index_příjemce> (např. e27ff0ac-87b5-4e1d-b644-5fc6029e2a11-0).Příklad: "e27ff0ac-87b5-4e1d-b644-5fc6029e2a11"

string

Kanál, který doručil (nebo se pokoušel doručit) zprávu. Jedna z: sms, viber, whatsapp_text, whatsapp_template.

integer

Unix timestamp události stavu.Příklad: 1700000000

object

Vlastní objekt payload, který jste připojili k původnímu požadavku zprávy, vrácený nezměněn. Použijte to k propojení události s vašimi vlastními záznamy.Příklad: { "campaign_id": "winter-sale" }

string

Vždy "outgoing" pro události sentMessage.

object

Příjemce této události.

Zobrazit pole to

string

Telefonní číslo příjemce v mezinárodním formátu.Příklad: "420777123456"

string

Aktuální stav doručení zprávy. Možné hodnoty:

Hodnota	Význam
`sending`	Zpráva je přenášena operatérovi.
`sent`	Zpráva byla přijata operatérem.
`delivered`	Operatér potvrdil doručení na zařízení příjemce.
`seen`	Příjemce zprávu otevřel (pouze Viber / WhatsApp).
`undelivered`	Doručení selhalo po odeslání zprávy.
`rejected`	Zpráva byla odmítnuta před odesláním (např. neplatné číslo, nedostatečný kredit).
`failed`	Došlo k neočekávané chybě.

string

Čitelný popis výsledku, volitelně s předponou číselného kódu v hranatých závorkách. Příklady: "[0] Delivered", "[307] Insufficient credit", "[131042] There was an error related to your payment method", "Unauthorized error".

object

Přítomné, když gateway je sms. Obsahuje detaily fakturace a směrování pro tuto SMS.

Zobrazit pole sms

string

Konkrétní použitá nastavení brány (např. high, direct, custom).

string

Jméno nebo číslo odesílatele použité pro tuto zprávu.

integer

Cílová země identifikovaná svým oficiálním MCC (Mobile Country Code).

integer

Cílový operatér identifikovaný svým oficiálním MNC (Mobile Network Code). 0 znamená neznámý nebo obecný operatér.

number

Cena této zprávy v českých korunách (CZK).

number

Cena této zprávy v Eurech (EUR).

integer

Počet odeslaných fakturacích segmentů (dlouhá SMS se dělí do více segmentů).

object

Přítomné, když gateway je viber. Obsahuje stejná podpole jako objekt sms: sender, country, operator, price_czk, price_eur, count.

object

Přítomné, když gateway je whatsapp_template. Obsahuje stejná podpole jako objekt sms.

object

Přítomné, když gateway je whatsapp_text. Obsahuje stejná podpole jako objekt sms.

Příkladový payload

[
  {
    "request_id": "bc36f3d1-d284-463a-921b-a3560c154649",
    "message_id": "e27ff0ac-87b5-4e1d-b644-5fc6029e2a11",
    "gateway": "sms",
    "timestamp": 1700000000,
    "payload": {
      "campaign_id": "winter-sale"
    },
    "type": "outgoing",
    "to": {
      "phone_number": "420777123456"
    },
    "result": "delivered",
    "result_info": "[0] Delivered",
    "sms": {
      "gateway": "high",
      "sender": "MujSender",
      "country": 230,
      "operator": 2,
      "price_czk": 0.85,
      "price_eur": 0.034,
      "count": 1
    }
  }
]

Událost incomingReplyMessage

SmsManager posílá událost incomingReplyMessage, když příjemce přímo odpoví na zprávu, kterou jste odeslali. Událost obsahuje request_id, message_id a payload vaší původní odchozí zprávy, takže můžete odpověď okamžitě spojit s jejím kontextem.

Reference polí

string

request_id původní odchozí zprávy, na kterou tato odpověď reaguje.

string

message_id původní odchozí zprávy, na kterou tato odpověď reaguje.

object

Objekt payload z vaší původní odchozí zprávy, vrácený pro korelaci.

string

Kanál, na kterém odpověď přišla. Jedna z: sms, viber, whatsapp. Poznámka: pro WhatsApp je hodnota gateway vždy whatsapp — pro příchozí zprávy se nedělí na whatsapp_text nebo whatsapp_template.

integer

Unix timestamp okamžiku, kdy příjemce odpověď odeslal. Pokud tato informace není k dispozici, je to čas, kdy SmsManager odpověď přijal.

string

Vždy "incoming" pro události incomingReplyMessage.

string

Telefonní číslo osoby, která odpověděla. V některých zemích není plně podporováno zasílání alfanumerických odesílatelů.

string

Číslo nebo ID odesílatele, které obdrželo odpověď (vaše virtuální číslo nebo jméno odesílatele).

string

Text odpovědi.

Příkladový payload

[
  {
    "request_id": "bc36f3d1-d284-463a-921b-a3560c154649",
    "message_id": "e27ff0ac-87b5-4e1d-b644-5fc6029e2a11",
    "payload": {
      "campaign_id": "winter-sale"
    },
    "gateway": "sms",
    "timestamp": 1700000100,
    "type": "incoming",
    "sender": "420777123456",
    "recipient": "420777654321",
    "body": "Děkuji!"
  }
]

Událost incomingMessage

SmsManager posílá událost incomingMessage, když přijde nová příchozí zpráva na jedno z vašich čísel, která není odpovědí na žádnou konkrétní odchozí zprávu — například zákazník píšící přímo na vaše dlouhé číslo nebo krátký kód.

Reference polí

string

Kanál, na kterém zpráva přišla. Jedna z: sms, viber, whatsapp.

integer

Unix timestamp okamžiku, kdy odesílatel zprávu odeslal.

string

Vždy "incoming" pro události incomingMessage.

string

Telefonní číslo osoby, která zprávu poslala.

string

Vaše číslo nebo ID odesílatele, které zprávu přijalo.

string

Text příchozí zprávy.

Příkladový payload

[
  {
    "gateway": "whatsapp",
    "timestamp": 1700000200,
    "type": "incoming",
    "sender": "420777123456",
    "recipient": "420777654321",
    "body": "Ahoj, mám otázku."
  }
]

Konfigurace webhook URL

Webhook URL můžete nastavit na dvou úrovních: 1. Callback na zprávu Zahrňte pole callback v těle požadavku POST /message nebo POST /messages:

{
  "body": "Vaše objednávka byla odeslána.",
  "to": [{ "phone_number": "420777123456" }],
  "callback": "https://example.com/webhooks/sms-delivery"
}

Callbacky na zprávu přepisují výchozí na účtu pro tu konkrétní zprávu. 2. Výchozí callback URL na účtu Nastavte záložní URL, která přijímá události pro všechny zprávy, které neurčují vlastní callback. Můžete ji aktualizovat přes SmsManager REST API:

curl -X POST https://rest-api.smsmngr.com/v1/apikey/update \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "default_callback_url": "https://example.com/webhooks/sms-default"
  }'

Vždy odpovídejte s HTTP 200 při přijetí webhook události. Pokud váš server vrátí chybový stav nebo je nedostupný, SmsManager může doručení opakovat. Rychlé vrácení 200 (před prováděním pomalého zpracování) udržuje váš webhook endpoint spolehlivý.

JSON API v2

JSON API v1

REST API

Verify API

WhatsApp Partner API

Referenční tabulky

Souhrn webhook událostí

Událost sentMessage

Reference polí

Příkladový payload

Událost incomingReplyMessage

Reference polí

Příkladový payload

Událost incomingMessage

Reference polí

Příkladový payload

Konfigurace webhook URL

​Souhrn webhook událostí

​Událost sentMessage

​Reference polí

​Příkladový payload

​Událost incomingReplyMessage

​Reference polí

​Příkladový payload

​Událost incomingMessage

​Reference polí

​Příkladový payload

​Konfigurace webhook URL

Souhrn webhook událostí

Událost sentMessage

Reference polí

Příkladový payload

Událost incomingReplyMessage

Reference polí

Příkladový payload

Událost incomingMessage

Reference polí

Příkladový payload

Konfigurace webhook URL