Rozwiązywanie problemów: najczęstsze błędy i jak je namierzyć
Debug w IVR API zaczyna się od korelacji: UniqueCallId → EventName → Action → wynik. Poniżej masz najczęstsze symptomy i najkrótszą ścieżkę diagnozy.
Zawsze zacznij od 5 rzeczy
- Weź UniqueCallId z logów.
- Sprawdź Event.EventName i Event.EventData.
- Sprawdź, co zwracałeś w Action i Session.step.
- Sprawdź czas odpowiedzi webhooka (ms) i limity/timeouty w panelu IVR API.
- Sprawdź, czy uruchomiło się działanie awaryjne (gdy endpoint nie odpowiada / błąd).
Zasada: w 90% przypadków odpowiedź jest w logach zebranych pod UniqueCallId + “co zwróciłem w Action”.
Symptom → przyczyna → szybka naprawa
1) “Cisza” po odebraniu / rozmowa urywa się
- 1002 (timeout) – aplikacja nie odpowiedziała w czasie,
- 1006 (zły JSON) – niepoprawna odpowiedź aplikacji,
- 2003 – błędne parametry akcji (literówka / brak pola).
Szybko: (1) ustaw/zweryfikuj działanie awaryjne w panelu, (2) w kodzie zwracaj “bezpieczną decyzję” gdy CRM/DB nie działa (np. kolejka ogólna zamiast czekania), (3) upewnij się, że zwracasz czysty JSON i poprawny Content-Type.
2) Wszystko odrzucane / integracja “nie widzi” wywołań (Hash/HTTPS)
- Hash w panelu ≠ Hash po stronie aplikacji (inny sekret / inny sposób liczenia),
- zmiana Hash w panelu bez aktualizacji aplikacji,
- problemy HTTPS / certyfikat (często 1003),
- firewall / allowlista IP blokuje ruch (często wygląda jak 1005).
Produkcyjnie: HTTPS + Hash weryfikowany po stronie aplikacji. Hash nie powinien trafiać do publicznych logów — jeśli wyciekł, zmień go w panelu.
3) CallStatus Busy/Noanswer i brak planu B
- brak obsługi CallStatus w state machine (EventName=CallStatus),
- zbyt długie próby połączeń “w kółko”,
- brak backupu (drugi cel / kolejka / komunikat).
Produkcyjny wzorzec: 1 próba primary → 1 próba backup → kolejka → komunikat → koniec. Bez pętli i bez “dialowania” 5 minut.
4) DTMF nie działa / częste timeouty / frustracja użytkowników
- za krótki Timeout w GetDTMF,
- zbyt długa zapowiedź przed zbieraniem cyfr,
- brak limitu prób i brak wyjścia do kolejki/konsultanta.
Najczęstsza poprawka: 2–3 próby (licznik w Session) i zawsze “wyjście” do kolejki. Lepiej krótsze IVR + człowiek niż perfekcyjna samoobsługa, która gubi rozmowy.
Najczęstsze kody błędów IVR API
| Kod | Opis (typowo) | Co sprawdzić |
|---|---|---|
| 1002 | aplikacja nie odpowiedziała w czasie | czas odpowiedzi endpointu, zależności z krótkimi timeoutami, fast-fallback |
| 1003 | problem z certyfikatem SSL | certyfikat + łańcuch, TLS, poprawność domeny |
| 1004 | błąd DNS (IP dla domeny) | DNS, rekordy, stabilność resolverów (czasem “działa rano, nie działa w szczycie”) |
| 1005 | błąd podczas łączenia z aplikacją | dostępność endpointu, firewall/WAF, allowlista, routing |
| 1006 | niepoprawna odpowiedź aplikacji | JSON, Content-Type, “echo”/BOM, błędy PHP, nieoczekiwany HTML |
| 2003 | złe parametry wybranej akcji | Type i parametry, literówki, wymagane pola (Prompt/Destination/Options) |
| 3001 | brak konta SIP dla połączeń wychodzących | Konfiguracja → konto telefoniczne (gdy używasz CallExternalNumber) |
W przypadku błędu request może zawierać pole Error (ErrorNo + ErrorMsg). Wtedy system wykonuje zaplanowane działanie awaryjne — a rozmowa nie powinna zależeć od tego, czy aplikacja “zdążyła odpowiedzieć”.
Wracasz do produkcji?
Przejdź po checkliście i powtórz testy negatywne (timeout, Busy/Noanswer, DTMF timeout).