## Co na vaši adresu chodí

BulkGate hlásí zpětně dvě věci: jak dopadly vaše odeslané zprávy a co vám lidé
odpověděli. Obojí dorazí jako HTTP požadavek na adresu, kterou máte nastavenou.

| Co dorazí | Jak to poznáte |
|:--|:--|
| Potvrzení o doručení | Parametr `status` s kódem stavu a `smsID` odeslané zprávy |
| Příchozí SMS nebo odpověď | Parametr `status` s hodnotou `10`, odesílatel v `from` a text v `message` |

Požadavek chodí metodou HTTP **GET** — hodnoty tedy najdete v query stringu.

> [!TIP]
> Při velkých objemech se vyplatí hromadná varianta: místo požadavku na každou
> zprávu dorazí jeden požadavek metodou POST s polem záznamů ve formátu JSON.
> Popisuje ji [Hromadné potvrzení o doručení](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/api-hromadne-potvrzeni-o-doruceni-a-prichozich-zpravach/).

## Kde se adresa nastavuje

Adresu si nastavíte sami v detailu své aplikace — na kartě `Nastavení` v části
`Web hooky` u dlaždice `Potvrzení o doručení`. Do pole `URL pro doručenky`
v okně, které se otevře, patří adresa začínající `http://` nebo `https://`.

![Okno Nastavení potvrzení o doručení s vypnutým hromadným zasíláním](docs:api-delivery-confirmations-and-incoming-sms/webhook-single_cs)

> [!IMPORTANT]
> Zaškrtávátko `Zasílat doručenky hromadně` nechte vypnuté — s ním se způsob
> doručení změní na dávky metodou POST a platí
> [Hromadné potvrzení o doručení](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/api-hromadne-potvrzeni-o-doruceni-a-prichozich-zpravach/).

Celý postup včetně ostatních voleb popisuje stránka
[Webhooky](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/webhooky/).

## Parametry potvrzení o doručení

| Parametr | Hodnota |
|:--|:--|
| `status` | Kód stavu zprávy — viz [stavy doručení](#stavy-doruceni) |
| `smsID` | Jednoznačné ID zprávy |
| `price` | Cena zprávy v kreditech |
| `channel` | Kanál, kterým zpráva šla (`sms`, `viber`, `whatsapp`, `rcs` a další) |
| `date` | Čas odeslání a doručení oddělený středníkem v časové zóně CET |

Hodnota `date` má tvar `RRMMDDHHMM;RRMMDDHHMM` — například
`1812141317;1812141318` znamená odesláno 14. 12. 2018 v 13:17 a doručeno
o minutu později.

## Parametry příchozí zprávy

Když má `status` hodnotu `10`, nejde o doručenku, ale o zprávu od příjemce.
Dorazí s jinou sadou parametrů:

| Parametr | Hodnota |
|:--|:--|
| `status` | Vždy `10` |
| `from` | Telefonní číslo odesílatele |
| `to` | Telefonní číslo příjemce, tedy vaše číslo |
| `message` | Text zprávy v kódování UTF-8 |
| `channel` | Kanál, kterým zpráva přišla |
| `smsdetails` | Podrobnosti včetně použitého protokolu a času přijetí |

## Stavy doručení

| Kód | Význam |
|:--|:--|
| `1` | Zpráva byla doručena |
| `2` | Zpráva čeká ve frontě na straně operátora — příjemce je momentálně nedostupný a doručení se zkusí znovu |
| `3` | Zprávu se nepodařilo doručit — příjemce je neznámý nebo trvale nedostupný |
| `10` | Příchozí zpráva nebo odpověď, ne doručenka |
| `13` | Zpráva byla přečtena (jen Viber) |

> [!NOTE]
> Stav `2` není konečný — na tutéž zprávu vám později dorazí další požadavek
> s výsledným stavem. Počítejte s tím, že `smsID` uvidíte víckrát.

## Ukázka zpracování

Skript rozliší doručenku od příchozí zprávy podle `status` a obojí zapíše do
vlastního logu:

```php
<?php declare(strict_types=1);

const STATUS = [
    1 => 'doručeno',
    2 => 'čeká u operátora',
    3 => 'nedoručeno',
    13 => 'přečteno',
];

$status = filter_input(INPUT_GET, 'status', FILTER_VALIDATE_INT);

function log_line(string $file, string $message): void
{
    file_put_contents(
        __DIR__ . "/$file.log",
        '[' . date('Y-m-d H:i:s') . '] ' . $message . PHP_EOL,
        FILE_APPEND
    );
}

if ($status === 10) // příchozí zpráva
{
    $from = filter_input(INPUT_GET, 'from') ?? '';
    $message = filter_input(INPUT_GET, 'message') ?? '';

    log_line('inbox', sprintf('Od: [%s] Zpráva: [%s]', $from, $message));
}
else if (isset(STATUS[$status])) // potvrzení o doručení
{
    $sms_id = filter_input(INPUT_GET, 'smsID') ?? '';
    $price = filter_input(INPUT_GET, 'price', FILTER_VALIDATE_FLOAT) ?: 0.0;

    log_line('delivery', sprintf('Zpráva [%s]: %s, cena %.4f', $sms_id, STATUS[$status], $price));
}
else
{
    http_response_code(400);
    exit;
}
```

> [!WARNING]
> Adresa musí odpovědět rychle a stavovým kódem `200`. Pomalé nebo chybující
> zpracování zdržuje doručování dalších hlášení — náročnou práci proto odložte
> na frontu a požadavek rovnou potvrďte.