## Hva som kommer til adressen din

BulkGate rapporterer to ting tilbake til deg: hvordan det gikk med meldingene du har sendt,
og hva folk svarte. Begge deler kommer som en HTTP-forespørsel til adressen du har angitt.

| Hva som kommer | Slik kjenner du det igjen |
|:--|:--|
| Leveringsrapport | Parameteren `status` med en statuskode og `smsID` for den sendte meldingen |
| Innkommende SMS eller svar | Parameteren `status` med verdien `10`, avsenderen i `from` og teksten i `message` |

Forespørselen kommer via HTTP **GET**, så du finner verdiene i query-strengen.

> [!TIP]
> Ved store volumer lønner massevarianten seg: i stedet for én forespørsel per melding
> kommer én enkelt POST-forespørsel med en matrise av poster i JSON. Den er beskrevet
> på [Leveringsbekreftelser for masseutsendinger](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-masseleveringsbekreftelser-og-innkommende-sms/).

## Hvor adressen angis

Du angir adressen selv i detaljene for applikasjonen din — på fanen `Innstillinger`,
i delen `Web hooks`, på kortet `Leveringsrapporter`. Feltet `URL-leveringsrapporter`
i vinduet som åpnes, tar imot en adresse som begynner med `http://`
eller `https://`.

![Innstillingsvinduet for leveringsrapporter med massesending slått av](docs:api-delivery-confirmations-and-incoming-sms/webhook-single_en)

> [!IMPORTANT]
> La avmerkingsboksen `Bulk DLRs - bulk forespørsel` være av — med den går leveringen
> over til grupper sendt via POST, og da gjelder
> [Leveringsbekreftelser for masseutsendinger](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-masseleveringsbekreftelser-og-innkommende-sms/)
> i stedet.

Hele fremgangsmåten med de øvrige alternativene er beskrevet på siden
[Webhooks](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/webhooks/).

## Parametere i leveringsrapporten

| Parameter | Verdi |
|:--|:--|
| `status` | Statuskoden for meldingen — se [leveringsstatuser](#leveringsstatuser) |
| `smsID` | Den unike ID-en til meldingen |
| `price` | Prisen på meldingen i kreditter |
| `channel` | Kanalen meldingen gikk gjennom (`sms`, `viber`, `whatsapp`, `rcs` og andre) |
| `date` | Tidspunktet for sending og levering atskilt med semikolon, i tidssonen CET |

Verdien `date` har formen `YYMMDDHHMM;YYMMDDHHMM` — for eksempel betyr
`1812141317;1812141318` sendt 14. desember 2018 kl. 13.17 og levert
ett minutt senere.

## Parametere for innkommende meldinger

Når `status` har verdien `10`, er dette ikke en leveringsrapport, men en melding
fra mottakeren. Den kommer med et annet sett parametere:

| Parameter | Verdi |
|:--|:--|
| `status` | Alltid `10` |
| `from` | Avsenderens telefonnummer |
| `to` | Mottakerens telefonnummer, altså ditt nummer |
| `message` | Teksten i meldingen i UTF-8 |
| `channel` | Kanalen meldingen kom gjennom |
| `smsdetails` | Detaljer, blant annet protokollen som ble brukt og tidspunktet for mottak |

## Leveringsstatuser

| Kode | Betydning |
|:--|:--|
| `1` | Meldingen ble levert |
| `2` | Meldingen står i kø hos operatøren — mottakeren er utilgjengelig for øyeblikket, og leveringen vil bli forsøkt på nytt |
| `3` | Meldingen kunne ikke leveres — mottakeren er ukjent eller permanent utilgjengelig |
| `10` | En innkommende melding eller et svar, ikke en leveringsrapport |
| `13` | Meldingen ble lest (bare Viber) |

> [!NOTE]
> Status `2` er ikke endelig — senere kommer en ny forespørsel med den endelige statusen for
> den samme meldingen. Regn med å se den samme `smsID` mer enn én gang.

## Et eksempel på behandling

Skriptet skiller en leveringsrapport fra en innkommende melding etter `status` og
skriver hver av dem til sin egen logg:

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

const STATUS = [
    1 => 'levert',
    2 => 'i kø hos operatøren',
    3 => 'ikke levert',
    13 => 'lest',
];

$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) // en innkommende melding
{
    $from = filter_input(INPUT_GET, 'from') ?? '';
    $message = filter_input(INPUT_GET, 'message') ?? '';

    log_line('inbox', sprintf('Fra: [%s] Melding: [%s]', $from, $message));
}
else if (isset(STATUS[$status])) // en leveringsrapport
{
    $sms_id = filter_input(INPUT_GET, 'smsID') ?? '';
    $price = filter_input(INPUT_GET, 'price', FILTER_VALIDATE_FLOAT) ?: 0.0;

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

> [!WARNING]
> Adressen må svare raskt og med statuskoden `200`. Treg eller
> feilende behandling forsinker leveringen av flere rapporter — legg derfor tungt
> arbeid i en kø og bekreft forespørselen med en gang.