> ## Documentation Index
> Fetch the complete documentation index at: https://developers.smsmanager.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  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.
</Tip>

## 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í

<ResponseField name="request_id" type="string">
  Jedinečný identifikátor původního API požadavku, který tuto zprávu odeslal.

  Příklad: `"bc36f3d1-d284-463a-921b-a3560c154649"`
</ResponseField>

<ResponseField name="message_id" type="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"`
</ResponseField>

<ResponseField name="gateway" type="string">
  Kanál, který doručil (nebo se pokoušel doručit) zprávu. Jedna z: `sms`, `viber`, `whatsapp_text`, `whatsapp_template`.
</ResponseField>

<ResponseField name="timestamp" type="integer">
  Unix timestamp události stavu.

  Příklad: `1700000000`
</ResponseField>

<ResponseField name="payload" type="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" }`
</ResponseField>

<ResponseField name="type" type="string">
  Vždy `"outgoing"` pro události `sentMessage`.
</ResponseField>

<ResponseField name="to" type="object">
  Příjemce této události.

  <Expandable title="pole to">
    <ResponseField name="phone_number" type="string">
      Telefonní číslo příjemce v mezinárodním formátu.

      Příklad: `"420777123456"`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="result" type="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ě.                                                        |
</ResponseField>

<ResponseField name="result_info" type="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"`.
</ResponseField>

<ResponseField name="sms" type="object">
  Přítomné, když `gateway` je `sms`. Obsahuje detaily fakturace a směrování pro tuto SMS.

  <Expandable title="pole sms">
    <ResponseField name="gateway" type="string">
      Konkrétní použitá nastavení brány (např. `high`, `direct`, `custom`).
    </ResponseField>

    <ResponseField name="sender" type="string">
      Jméno nebo číslo odesílatele použité pro tuto zprávu.
    </ResponseField>

    <ResponseField name="country" type="integer">
      Cílová země identifikovaná svým oficiálním MCC (Mobile Country Code).
    </ResponseField>

    <ResponseField name="operator" type="integer">
      Cílový operatér identifikovaný svým oficiálním MNC (Mobile Network Code). `0` znamená neznámý nebo obecný operatér.
    </ResponseField>

    <ResponseField name="price_czk" type="number">
      Cena této zprávy v českých korunách (CZK).
    </ResponseField>

    <ResponseField name="price_eur" type="number">
      Cena této zprávy v Eurech (EUR).
    </ResponseField>

    <ResponseField name="count" type="integer">
      Počet odeslaných fakturacích segmentů (dlouhá SMS se dělí do více segmentů).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="viber" type="object">
  Přítomné, když `gateway` je `viber`. Obsahuje stejná podpole jako objekt `sms`: `sender`, `country`, `operator`, `price_czk`, `price_eur`, `count`.
</ResponseField>

<ResponseField name="whatsapp_template" type="object">
  Přítomné, když `gateway` je `whatsapp_template`. Obsahuje stejná podpole jako objekt `sms`.
</ResponseField>

<ResponseField name="whatsapp_body" type="object">
  Přítomné, když `gateway` je `whatsapp_text`. Obsahuje stejná podpole jako objekt `sms`.
</ResponseField>

### Příkladový payload

```json theme={null}
[
  {
    "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í

<ResponseField name="request_id" type="string">
  `request_id` původní odchozí zprávy, na kterou tato odpověď reaguje.
</ResponseField>

<ResponseField name="message_id" type="string">
  `message_id` původní odchozí zprávy, na kterou tato odpověď reaguje.
</ResponseField>

<ResponseField name="payload" type="object">
  Objekt `payload` z vaší původní odchozí zprávy, vrácený pro korelaci.
</ResponseField>

<ResponseField name="gateway" type="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`.
</ResponseField>

<ResponseField name="timestamp" type="integer">
  Unix timestamp okamžiku, kdy příjemce odpověď odeslal. Pokud tato informace není k dispozici, je to čas, kdy SmsManager odpověď přijal.
</ResponseField>

<ResponseField name="type" type="string">
  Vždy `"incoming"` pro události `incomingReplyMessage`.
</ResponseField>

<ResponseField name="sender" type="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ů.
</ResponseField>

<ResponseField name="recipient" type="string">
  Číslo nebo ID odesílatele, které obdrželo odpověď (vaše virtuální číslo nebo jméno odesílatele).
</ResponseField>

<ResponseField name="body" type="string">
  Text odpovědi.
</ResponseField>

### Příkladový payload

```json theme={null}
[
  {
    "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í

<ResponseField name="gateway" type="string">
  Kanál, na kterém zpráva přišla. Jedna z: `sms`, `viber`, `whatsapp`.
</ResponseField>

<ResponseField name="timestamp" type="integer">
  Unix timestamp okamžiku, kdy odesílatel zprávu odeslal.
</ResponseField>

<ResponseField name="type" type="string">
  Vždy `"incoming"` pro události `incomingMessage`.
</ResponseField>

<ResponseField name="sender" type="string">
  Telefonní číslo osoby, která zprávu poslala.
</ResponseField>

<ResponseField name="recipient" type="string">
  Vaše číslo nebo ID odesílatele, které zprávu přijalo.
</ResponseField>

<ResponseField name="body" type="string">
  Text příchozí zprávy.
</ResponseField>

### Příkladový payload

```json theme={null}
[
  {
    "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`:

```json theme={null}
{
  "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:

```bash theme={null}
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"
  }'
```

<Note>
  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ý.
</Note>