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, WhatsApp a RCS. 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, rcs.

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.

Show 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 operátorovi.
`sent`	Zpráva byla přijata operátorem.
`delivered`	Operátor 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

Nepovinné — pole může chybět nebo být prázdné. Doplňující informace k výsledku ve formátu [kód] Popis. SmsManager ho vyplňuje u zamítnutých zpráv, například "[307] Insufficient credit". Může obsahovat i chybu od poskytovatele kanálu, například "[131042] There was an error related to your payment method". Úplný seznam hodnot najdete v přehledu chyb.

object

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

Show 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ý operátor identifikovaný svým oficiálním MNC (Mobile Network Code). 0 znamená neznámý nebo obecný operátor.

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

Objektem params._incoming můžete zprávě při odeslání nastavit automatické odpovědi podle klíčového slova nebo tlačítka a vlastní callback pro její příchozí události. Ten dostává odpovědi, klepnutí na tlačítka WhatsApp a RCS i opt-out klíčová slova navíc k hlavnímu poli callback. Klepnutí na tlačítko nese objekt whatsapp nebo rcs se stisknutým tlačítkem. Postup popisuje návod Automatické odpovědi a příchozí zprávy.

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, rcs. 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. Pokud zpráva obsahuje jen médium s popiskem, je zde popisek média.

object

Nepovinné. Příloha odpovědi, například obrázek, dokument nebo sdílená poloha. Posílá se jen tehdy, když zpráva médium obsahuje. Popis polí najdete v sekci Objekt media.

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, rcs.

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. Pokud zpráva obsahuje jen médium s popiskem, je zde popisek média.

object

Nepovinné. Příloha zprávy, například obrázek, dokument nebo sdílená poloha. Posílá se jen tehdy, když zpráva médium obsahuje. Popis polí najdete v sekci Objekt media.

Příkladový payload

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

Objekt media

Události incomingReplyMessage a incomingMessage obsahují objekt media, když příchozí zpráva z WhatsAppu nebo RCS nese přílohu. Může jít o obrázek, video, audio, dokument, nálepku, sdílenou polohu nebo kontaktní karty. U souborů SmsManager uloží přílohu na trvalou veřejnou URL v poli url. Pokud se soubor uložit nepodaří, url chybí a místo něj je nastaveno pole error. Ostatní metadata dorazí i tak.

Reference polí

string

Typ přílohy. Jedna z: image, video, audio, document, sticker, location, contacts.

string

Trvalá veřejná URL uloženého souboru. Chybí, pokud se soubor nepodařilo uložit — pak je nastaveno error.

string

MIME typ souboru, jak ho nahlásil kanál.Příklad: "image/jpeg"

string

Původní název souboru (u dokumentů).

string

Popisek odeslaný spolu s médiem. Pokud zpráva nemá text, doručí se popisek také jako body.

integer

Velikost souboru v bajtech, pokud je známa.

boolean

Zda je nálepka animovaná. Pouze u nálepek (sticker).

string

Trvalá veřejná URL uloženého náhledu. Pouze u RCS.

object

Sdílená poloha. Pouze když type je location.

Show pole location

number

Zeměpisná šířka.

number

Zeměpisná délka.

string

Název místa.

string

Adresa místa.

object[]

Sdílené kontaktní karty v podobě, v jaké je poskytl kanál. Pouze když type je contacts.

string

ID média nebo zprávy přidělené poskytovatelem kanálu.

string

Nastaví se místo url, pokud se soubor nepodařilo uložit. Jedna z: download_failed, too_large, no_token.

Příkladový payload s médiem

[
  {
    "request_id": "bc36f3d1-d284-463a-921b-a3560c154649",
    "message_id": "e27ff0ac-87b5-4e1d-b644-5fc6029e2a11",
    "payload": {
      "campaign_id": "winter-sale"
    },
    "gateway": "whatsapp",
    "timestamp": 1700000000,
    "type": "incoming",
    "sender": "420777123456",
    "recipient": "420777654321",
    "body": "fotka poškozeného balíku",
    "media": {
      "type": "image",
      "url": "https://smsmngr-inbound-media.s3.eu-central-1.amazonaws.com/3f7a1c9b2e4d5f60718293a4b5c6d7e8.jpg",
      "mime_type": "image/jpeg",
      "caption": "fotka poškozeného balíku",
      "size": 245731,
      "provider_id": "1234567890123456"
    }
  }
]

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

HTTP/XML API

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

Objekt media

Reference polí

Příkladový payload s médiem

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

​Objekt media

​Reference polí

​Příkladový payload s médiem

​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

Objekt media

Reference polí

Příkladový payload s médiem

Konfigurace webhook URL