Open in
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 czacie | Co wywołuje Twój bot | Co się dzieje |
|---|---|---|
| Wysyłasz „Zadzwoń do Comcast i ustal przewidywany czas usunięcia awarii” | POST /v1/call z wiadomością jako context | Agent wykonuje połączenie. Twój bot otwiera wątek dla połączenia |
| Obserwujesz wątek | Odbiera webhooki telephony.turn | Każda wypowiedź agenta lub drugiej osoby pojawia się w wątku |
| Odpowiadasz w wątku w trakcie połączenia | POST /v1/calls/{call_id}/whisper | Agent otrzymuje Twoją notatkę prywatnie i podejmuje działanie. Druga osoba nigdy jej nie słyszy |
| Odpowiadasz na pytanie agenta | Twój endpoint narzędzia zwraca odpowiedź lub dostarcza ją później przez POST /v1/calls/{call_id}/tool-results | Agent kontynuuje połączenie, wykorzystując tę odpowiedź; w trybie oczekiwania druga osoba w tym czasie słyszy muzykę na czekanie |
| Odczytujesz wynik | Odbiera webhooki telephony.complete | Twó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ę
contextdla 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.turnoraztelephony.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ńcowesummarywymaga 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_idkoperty i sortuj wedługposition. 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
timeoutnarzę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.turnodbywa 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.