Strona główna -> Dokumentacja -> Akcje API

Akcje API: referencja

W odpowiedzi webhooka zwracasz obiekt Action — czyli decyzję, co platforma ma zrobić teraz. Najlepsza praktyka: jedna akcja na jeden krok (Play → zdarzenie, GetDTMF → zdarzenie, Call… → CallStatus).

Format odpowiedzi

{
  "Action": { "Type": "Play", "Prompt": "1" },
  "Session": { "step": "welcome" }
}

Session jest opcjonalne. Używaj go do trzymania kroku rozmowy i liczników (np. prób DTMF), a nie do przechowywania dużych danych.

Play / Answer / Hangup / Wait

Play

{
  "Action": { "Type": "Play", "Prompt": "1" },
  "Session": { "step": "play_welcome" }
}

Answer

{
  "Action": { "Type": "Answer" },
  "Session": { "step": "answer" }
}

Hangup

{
  "Action": { "Type": "Hangup" },
  "Session": { "step": "end" }
}

Wait

Krótka pauza (np. między komunikatami). Warto trzymać się krótkich czasów, żeby nie “marnować” rozmowy.

{
  "Action": { "Type": "Wait", "WaitTime": "2" },
  "Session": { "step": "wait" }
}

GetDTMF

GetDTMF zbiera cyfry z klawiatury telefonu. Po wykonaniu akcji dostaniesz kolejne zdarzenie z wynikiem (cyfry albo timeout) — i wtedy podejmujesz następny krok.

Prompt – zapowiedź przed zbieraniem (numer komunikatu z panelu),
Timeout – czas (ms) na kolejną cyfrę,
MaxDigits – limit cyfr,
# zwykle kończy wpisywanie (czytelne UX).

{
  "Action": { "Type": "GetDTMF", "Prompt": "1", "Timeout": "1200", "MaxDigits": "10" },
  "Session": { "step": "ask_id", "tries": 1 }
}

Dobra praktyka: 2–3 próby (licznik w Session), potem fallback do kolejki lub konsultanta.

Call… (routing) i CallStatus

Akcje Call są używane do routingu: do osoby, numeru lub obiektu. Wynik próby połączenia dostaniesz jako CallStatus w kolejnym webhooku (np. Answer/Busy/Noanswer/Cancel/Error).

CallExternalNumber

{
  "Action": {
    "Type": "CallExternalNumber",
    "Destination": "501234567",
    "Options": "PlayCallStatus,Timeout=20"
  },
  "Session": { "step": "dial_sales" }
}

CallLocalNumber

{
  "Action": {
    "Type": "CallLocalNumber",
    "Destination": "48221234567",
    "Options": "PlayCallStatus,Timeout=30"
  },
  "Session": { "step": "dial_local" }
}

CallByObjectLogin

{
  "Action": {
    "Type": "CallByObjectLogin",
    "Destination": "obiekt001",
    "Options": "PlayCallStatus,Timeout=30"
  },
  "Session": { "step": "dial_object" }
}

Najczęściej używane opcje w Options: Timeout oraz PlayCallStatus. Resztę dobieraj dopiero, gdy masz stabilny flow i logi pokazują, że to potrzebne.

Chcesz gotowe wzorce?

Jeśli masz już podstawowe akcje, przejdź do gotowych flow (DTMF + retries + routing + fallback).

Przykłady kodu Kolejki i routing