Alert API (Beta)

Beta. Alert API jest w fazie testów. Format zapytań, odpowiedzi i webhooków może się jeszcze zmienić. Prosimy nie traktować go jako ostatecznego i zgłaszać wszelkie uwagi.

Alert API dzwoni na jeden lub wiele numerów, odtwarza komunikat (syntezator mowy lub plik dźwiękowy), opcjonalnie zbiera potwierdzenie z klawiatury telefonu (DTMF), wykrywa automatyczną sekretarkę i raportuje wynik każdego połączenia.

W odróżnieniu od Voice API nie trzeba budować logiki połączenia z obiektów - wystarczy podać numery, komunikat i sposób potwierdzenia. Typowe zastosowania:

• alarm z potwierdzeniem - dzwonimy do wszystkich naraz, pierwsza osoba, która naciśnie 1, potwierdza alarm, a pozostałe połączenia są kończone,
• lista eskalacyjna - dzwonimy po kolei, aż ktoś potwierdzi,
• powiadomienie - komunikat do odsłuchania, bez potwierdzania.

Zasady wspólne z pozostałymi API:

• autoryzacja tokenem JWT w nagłówku Authorization: Bearer <token> (patrz Autentykacja),
• każda odpowiedź zawiera pole result o wartości OK lub error; w przypadku błędu pole error zawiera jego opis,
• numery telefonów w formacie E.164 bez znaku + i bez 00, np. 48501000000.

Utworzenie alertu

Alarm z potwierdzeniem - dzwonimy do dwóch osób jednocześnie, pierwsze naciśnięcie 1 potwierdza alarm:

curl --header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAoMS0Iiwi" \
--request POST \
--data '{
    "to": ["48600100200", "48600100201"],
    "from": "48221234567",
    "message": {
        "tts": {
            "text": "Alarm w serwerowni. Naciśnij 1 aby potwierdzić, 0 aby odrzucić.",
            "lang": "pl-PL/Maja"
        }
    },
    "dtmf": {"accept": "1", "reject": "0", "timeout": 10},
    "confirmation": {
        "accepted": {"tts": {"text": "Dziękujemy, alarm potwierdzony.", "lang": "pl-PL/Maja"}}
    },
    "amd": {"on_machine": "hangup"},
    "webhook": "https://twoj.serwer.pl/alerty",
    "reference": "incydent-4711"
}' \
https://api.vpbx.pl/api/v1/alerts

Lista eskalacyjna z nagranym komunikatem - dzwonimy po kolei, a gdy odbierze poczta głosowa, zostawiamy wiadomość:

{
    "to": ["48600100200", "48600100201", "48600100202"],
    "from": "48221234567",
    "mode": "sequential",
    "message": {"playfile": {"url": "https://twoj.serwer.pl/alarm.wav"}},
    "dtmf": {},
    "amd": {"on_machine": "leave_message"}
}

Powiadomienie na jeden numer, bez potwierdzania:

{
    "to": "48600100200",
    "from": "48221234567",
    "message": {"tts": {"text": "Dziś o 22:00 planowana przerwa serwisowa.", "lang": "pl-PL/Maja"}},
    "repeat": 2
}

Parametry zapytania

Nieznane pola w zapytaniu powodują błąd 400.

Z włączonym wykrywaniem automatycznej sekretarki (amd) komunikat zaczyna się po rozpoznaniu, że odebrał człowiek - zwykle 1-3 sekundy po odebraniu połączenia.

Odpowiedź - alert przyjęty

Połączenia są kolejkowane i wykonywane w tle; odpowiedź wraca od razu.

{
    "result": "OK",
    "alert_id": "1f0c6a52-3a7e-4b8e-9d0a-5c1b2f7e8a90",
    "status": "in_progress",
    "mode": "parallel",
    "confirmable": true,
    "stop_on_accept": true,
    "reference": "incydent-4711",
    "created_at": "2026-11-05T10:00:00Z",
    "calls": [
        {"call_id": "8a2e4c1d-5b6f-4e7a-9c8d-1e2f3a4b5c6d", "to": "48600100200", "from": "48221234567", "status": "queued"},
        {"call_id": "93b17f0e-2c3d-4a5b-8e9f-0a1b2c3d4e5f", "to": "48600100201", "from": "48221234567", "status": "queued"}
    ]
}

Odpowiedź - odrzucenie alertu

{
    "result": "error",
    "error": "to: \"+48600100200\" is not valid, use E.164 digits without \"+\" or \"00\": 3-15 digits starting with the country code, e.g. 48600100200"
}

Przy braku stawki lub środków odpowiedź zawiera dodatkowo listę numerów, których dotyczy błąd:

{
    "result": "error",
    "error": "insufficient credit",
    "numbers": ["48600100201"]
}

Kody błędów HTTP

Środki sprawdzane są dla każdego numeru przed przyjęciem alertu oraz ponownie tuż przed wykonaniem każdego połączenia. Czas trwania połączenia jest ograniczony do kwoty dostępnej na koncie.

Status alertu

curl --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAoMS0Iiwi" \
--request GET \
https://api.vpbx.pl/api/v1/alerts/1f0c6a52-3a7e-4b8e-9d0a-5c1b2f7e8a90

Odpowiedź ma ten sam format co przy utworzeniu alertu, z aktualnym stanem połączeń:

{
    "result": "OK",
    "alert_id": "1f0c6a52-3a7e-4b8e-9d0a-5c1b2f7e8a90",
    "status": "completed",
    "outcome": "confirmed",
    "mode": "parallel",
    "confirmable": true,
    "stop_on_accept": true,
    "accepted_by": "8a2e4c1d-5b6f-4e7a-9c8d-1e2f3a4b5c6d",
    "reference": "incydent-4711",
    "created_at": "2026-11-05T10:00:00Z",
    "completed_at": "2026-11-05T10:00:22Z",
    "calls": [
        {
            "call_id": "8a2e4c1d-5b6f-4e7a-9c8d-1e2f3a4b5c6d",
            "to": "48600100200",
            "from": "48221234567",
            "status": "completed",
            "result": "accepted",
            "digit": "1",
            "amd_result": "human",
            "dialed_at": "2026-11-05T10:00:00Z",
            "answered_at": "2026-11-05T10:00:06Z",
            "ended_at": "2026-11-05T10:00:21Z",
            "duration_total": 21,
            "duration_answered": 15
        },
        {
            "call_id": "93b17f0e-2c3d-4a5b-8e9f-0a1b2c3d4e5f",
            "to": "48600100201",
            "from": "48221234567",
            "status": "completed",
            "result": "cancelled",
            "dialed_at": "2026-11-05T10:00:00Z",
            "ended_at": "2026-11-05T10:00:16Z",
            "duration_total": 16,
            "duration_answered": 0
        }
    ]
}

Wyniki dostępne są przez 7 dni od zakończenia alertu. Alert innego konta zwraca 404 (alert not found).

Pola alertu

Pola połączenia

Wyniki połączeń

Przyczyny (result_reason)

Pole result_reason wyjaśnia, dlaczego połączenie zakończyło się wynikiem busy, no_answer lub failed, zgodnie z informacją z sieci odbiorcy:

Anulowanie alertu

curl --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAoMS0Iiwi" \
--request DELETE \
https://api.vpbx.pl/api/v1/alerts/1f0c6a52-3a7e-4b8e-9d0a-5c1b2f7e8a90

{
    "result": "OK",
    "alert_id": "1f0c6a52-3a7e-4b8e-9d0a-5c1b2f7e8a90",
    "status": "cancelling"
}

Zakolejkowane połączenia są anulowane, trwające - rozłączane. status ma wartość cancelling, dopóki trwa rozłączanie, lub completed, jeśli alert był już zakończony. Dla każdego rozłączonego połączenia wysyłany jest webhook alert-call-completed, a na końcu alert-completed z outcome: cancelled (lub confirmed, jeśli ktoś zdążył potwierdzić).

Webhooki

Wyniki wysyłane są na adres z pola webhook, metodą z webhook_method. W razie niepowodzenia dostarczenie jest ponawiane. Ten sam webhook może dotrzeć więcej niż raz - do wykrywania duplikatów należy używać event_type oraz call.call_id / alert_id.

alert-call-completed

Wysyłany raz dla każdego numeru, po zakończeniu połączenia.

{
    "event_type": "alert-call-completed",
    "timestamp": "2026-11-05T10:00:21Z",
    "alert_id": "1f0c6a52-3a7e-4b8e-9d0a-5c1b2f7e8a90",
    "reference": "incydent-4711",
    "call": {
        "call_id": "8a2e4c1d-5b6f-4e7a-9c8d-1e2f3a4b5c6d",
        "to": "48600100200",
        "from": "48221234567",
        "status": "completed",
        "result": "accepted",
        "digit": "1",
        "amd_result": "human",
        "dialed_at": "2026-11-05T10:00:00Z",
        "answered_at": "2026-11-05T10:00:06Z",
        "ended_at": "2026-11-05T10:00:21Z",
        "duration_total": 21,
        "duration_answered": 15
    }
}

alert-completed

Wysyłany raz, po zakończeniu wszystkich połączeń alertu (także tych rozłączonych, bo potwierdził ktoś inny).

{
    "event_type": "alert-completed",
    "timestamp": "2026-11-05T10:00:22Z",
    "alert_id": "1f0c6a52-3a7e-4b8e-9d0a-5c1b2f7e8a90",
    "reference": "incydent-4711",
    "outcome": "confirmed",
    "accepted_by": "8a2e4c1d-5b6f-4e7a-9c8d-1e2f3a4b5c6d",
    "summary": {"accepted": 1, "cancelled": 1},
    "calls": [ ... ]
}