ThunderPhone v3 już działa.Uruchom samodzielnie, od 2¢/min.Przeczytaj komunikat

Developer cookbook

Uruchamiaj połączenia ze Slacka lub aplikacji czatowej

Zbuduj własnego bota dla Slacka, Teams lub czatu internetowego, który rozpoczyna połączenia, śledzi je na żywo, kieruje agentem i odpowiada na jego pytania, korzystając z publicznego API.

Możesz sterować agentem z aplikacji czatu, której Twój zespół już używa. Wiadomość rozpoczyna połączenie. Połączenie przebiega na żywo w wątku. Odpowiedź w wątku kieruje działaniem agenta. Gdy agent potrzebuje decyzji, pyta Cię tam i czeka na Twoją odpowiedź.

ThunderPhone nie hostuje tego bota za Ciebie. Ty (lub Twój agent programistyczny) tworzysz mały serwer, który łączy aplikację czatu z publicznym API. Ta strona pokazuje elementy rozwiązania. Są takie same dla Slacka, Microsoft Teams, Discorda lub prywatnej strony czatu internetowego; przykłady używają Slacka.

Jak to działa

Co robisz na czacieCo wywołuje Twój botCo się dzieje
Wysyłasz „Zadzwoń do Comcast i ustal przewidywany czas usunięcia awarii”POST /v1/call z wiadomością jako contextAgent wykonuje połączenie. Twój bot otwiera wątek dla połączenia
Obserwujesz wątekOdbiera webhooki telephony.turnKażda wypowiedź agenta lub drugiej osoby pojawia się w wątku
Odpowiadasz w wątku w trakcie połączeniaPOST /v1/calls/{call_id}/whisperAgent otrzymuje Twoją notatkę prywatnie i podejmuje działanie. Druga osoba nigdy jej nie słyszy
Odpowiadasz na pytanie agentaTwój endpoint narzędzia zwraca odpowiedź lub dostarcza ją później przez POST /v1/calls/{call_id}/tool-resultsAgent kontynuuje połączenie, wykorzystując tę odpowiedź; w trybie oczekiwania druga osoba w tym czasie słyszy muzykę na czekanie
Odczytujesz wynikOdbiera webhooki telephony.completeTwój bot publikuje podsumowanie i wynik

Twój bot przechowuje jedno mapowanie: który wątek czatu należy do którego call_id.

Zanim zaczniesz

  • Klucz API, przechowywany na serwerze, nigdy w przeglądarce ani na czacie. Utwórz go w Integracje → klucze API (zobacz Utwórz serwerowy klucz API).
  • Numer z włączonymi połączeniami wychodzącymi i agent do realizacji połączeń. Wiadomość staje się context dla danego połączenia, więc jeden ogólny agent obsługuje każde zadanie.
  • Serwer, który może odbierać webhooki, taki jak Railway, Fly.io, Render lub własny host.
  • Punkt końcowy webhooka wskazujący na ten serwer i subskrybujący telephony.turn oraz telephony.complete. Zdarzenia tur są wysyłane tylko do punktów końcowych, które je wymieniają. Zobacz Webhooki. Zdarzenia tur wymagają włączonego nagrywania rozmów agenta, a końcowe summary wymaga włączenia przez agenta ustawienia Generuj podsumowanie rozmowy; bez nich te pola pozostają puste.
  • Własna aplikacja czatowa. W przypadku Slack utwórz aplikację w swoim obszarze roboczym na api.slack.com/apps.

1. Rozpocznij połączenie z wiadomości

Gdy bot otrzyma wiadomość (wiadomość bezpośrednią lub wzmiankę @), natychmiast potwierdź żądanie Slacka (Slack ponawia wszystko, co nie zostanie potwierdzone w ciągu 3 sekund), a resztę wykonaj w tle. Sprawdź, czy nadawca ma uprawnienia do wykonywania połączeń, a następnie rozpocznij połączenie z wiadomością jako context:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

Zapisz zwrócone call_id dla wątku Slacka (channel wraz z wiadomością ts) i odpowiedz w wątku („Dzwonię…”). Zbuduj idempotency_key z kanału i ts wiadomości (ts jest unikalne tylko w obrębie swojego kanału), aby ponowione zdarzenie Slacka nie wykonało drugiego połączenia. Jeśli żądanie wskazuje osobę zamiast numeru, bot najpierw wyszukuje jej numer. ThunderPhone wybiera tylko przesłany przez Ciebie to_number.

2. Śledź połączenie w wątku

Każdy webhook telephony.turn zawiera call_id, mówcę (role: assistant dla agenta, user dla drugiej osoby), text oraz position tury. Wyszukaj wątek według call_id i opublikuj wpis.

  • Weryfikuj każdy webhook przed wykonaniem jakiejkolwiek akcji. Zobacz Weryfikowanie podpisów webhooków.
  • Usuwaj duplikaty na podstawie event_id koperty i sortuj według position. Dostarczanie odbywa się co najmniej raz, a tury mogą nadejść w niewłaściwej kolejności.
  • Grupuj wpisy, jeśli aktywne połączenie mogłoby zalać wątek; publikowanie co kilka sekund czyta się lepiej niż jedna wiadomość na wiersz.

Gdy nadejdzie telephony.complete, opublikuj sposób zakończenia połączenia (jego status i end_reason), summary oraz wszelkie wyodrębnione dane, a następnie zamknij wątek. Informacje o polach znajdziesz w Zakończenie połączenia.

3. Kieruj połączeniem z wątku

Gdy ktoś odpowie w wątku aktywnego połączenia, wyślij odpowiedź jako szept, chyba że agent czeka na odpowiedź na pytanie (krok 4), w takim przypadku odpowiedź jest właściwą odpowiedzią:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

Agent słyszy go prywatnie i uwzględnia w swojej następnej turze; druga osoba nigdy nie słyszy samego szeptu. Szept ma od 1 do 1000 znaków. Kod 409 oznacza, że połączenie nie jest już aktywne: poinformuj wątek, że połączenie się zakończyło.

4. Pozwól agentowi zadać ci pytanie

Dodaj agentowi narzędzie, na przykład ask_owner z jednym parametrem question, które wywołuje twój serwer. Utwórz je jako połączenie API i połącz z agentem. Każde żądanie narzędzia zawiera identyfikator połączenia w nagłówku X-ThunderPhone-Call-ID.

Są trzy sposoby na otrzymanie odpowiedzi.

Wstrzymaj połączenie (do 10 minut). Ustaw narzędzie w trybie wstrzymania: spec.wait_mode "hold" oraz spec.timeout na maksymalnie 600 sekund (bez limitu czasu wstrzymanie trwa 20 sekund), za pośrednictwem API lub poproś Zeus o ich ustawienie (edytory aplikacji nie mają jeszcze żadnego z tych pól). Punkt końcowy publikuje pytanie w wątku połączenia i natychmiast odpowiada wynikiem oczekującym:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

Rozmówca słyszy jedną komunikat od agenta, a następnie muzykę podczas oczekiwania. W menu telefonicznym lub na poczcie głosowej agent przekazuje zamiast tego komunikaty głosowe, a agent pełnodupleksowy nie wstrzymuje rozmowy: otrzymuje odpowiedź oczekującą jako wynik. Gdy odpowiedź pojawi się w wątku, dostarcz ją za pomocą POST /v1/calls/{call_id}/tool-results:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

Muzyka cichnie, a agent kontynuuje rozmowę, korzystając z twojej odpowiedzi. Jeśli nikt nie odpowie przed upływem timeout, agent otrzyma informację, że nie nadeszła odpowiedź, i zaproponuje rozmówcy dalsze kroki. Gdy pytanie dotyczące połączenia oczekuje na odpowiedź, następna odpowiedź w jego wątku stanowi odpowiedź: dostarcz ją jako wynik narzędzia i nie wysyłaj jej dodatkowo jako szeptu (szept dociera do agenta dopiero po zakończeniu działania narzędzia). Zobacz Długie oczekiwanie.

Czekaj w żądaniu (do 3 minut). Twój punkt końcowy publikuje pytanie, czeka na odpowiedź i ją zwraca, na przykład {"answer": "Yes, book Tuesday at 10."}. Ustaw spec.timeout narzędzia za pomocą API, maksymalnie na 180 sekund (domyślna wartość to 20). Ustaw dla punktu końcowego własny limit czasu o kilka sekund krótszy (na przykład 170 sekund), aby gdy nikt nie odpowie, nadal zwracał coś, na czym agent może działać, na przykład {"answer": null, "note": "No reply yet. Offer to take a message."}. Narzędzie, które osiągnie timeout, dociera do agenta jako błąd, a twój host musi utrzymywać żądanie otwarte przez tak długi czas. Podczas oczekiwania agent informuje rozmówcę, że sprawdza, po około 12 sekundach mówi, że nadal nad tym pracuje, a następnie przekazuje krótką aktualizację mniej więcej co 15 sekund. Tryb wstrzymania działa również tutaj: ustaw spec.wait_mode na "hold", a rozmówca usłyszy muzykę zamiast komunikatów.

Odpowiedz szeptem. Twój punkt końcowy publikuje pytanie i natychmiast zwraca odpowiedź, na przykład {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Gdy nadejdzie odpowiedź, wyślij ją jako szept (krok 3), a agent natychmiast na nią odpowie. Użyj tego w przypadku odpowiedzi, które mogą potrwać dłużej niż 10 minut. Połączenie nie jest wstrzymywane: twój prompt powinien poinstruować agenta, co ma robić w międzyczasie, na przykład podtrzymywać rozmowę z rozmówcą lub zaproponować oddzwonienie.

W każdym przypadku określ w prompcie agenta, kiedy używać narzędzia i co powiedzieć rozmówcy podczas oczekiwania:

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

Limity, które należy uwzględnić

  • Twój endpoint musi odpowiedzieć w ramach timeout narzędzia, maksymalnie w ciągu 180 sekund. Narzędzie w trybie wstrzymania może utrzymywać połączenie w stanie oczekiwania przez maksymalnie 600 sekund z oczekującym wynikiem.
  • Gdy narzędzie oczekuje, agent nie odpowiada drugiej osobie. W trybie wstrzymania słyszy ona muzykę, a w przeciwnym razie krótkie komunikaty głosowe.
  • Szept może mieć maksymalnie 1000 znaków.
  • Dostarczanie telephony.turn odbywa się co najmniej raz i może następować w niewłaściwej kolejności.

Lista kontrolna bezpieczeństwa

  • Przechowuj klucz API na swoim serwerze.
  • Weryfikuj podpisy ThunderPhone w webhookach i żądaniach narzędzi oraz sekret podpisywania Slacka w żądaniach Slacka. Dwa podpisy ThunderPhone używają różnych sekretów: dostarczenia webhooków używają własnego sekretu endpointu webhooka, a żądania narzędzi używają sekretu webhooka Twojej organizacji z GET /v1/webhook.
  • Zdecyduj, kto może rozpoczynać połączenia: sprawdzaj identyfikator użytkownika Slacka przed ich wykonaniem.
  • Połączenia wychodzące podlegają tym samym zasadom co wszystkie pozostałe. Zobacz Przepisy dotyczące połączeń wychodzących.

Zbuduj to z agentem programistycznym

Skieruj swojego agenta programistycznego do serwera MCP dokumentacji oraz na tę stronę i poproś o „bota Slack dla mojego agenta ThunderPhone, który postępuje zgodnie z tym przewodnikiem”. Zeus, asystent w aplikacji ThunderPhone, może skonfigurować część agenta (endpoint webhooka, narzędzie i linie promptu) oraz napisać kod startowy bota na czacie.