Open in
Spúšťajte hovory zo Slacku alebo chatovacej aplikácie
Vytvorte si vlastného bota pre Slack, Teams alebo webový chat, ktorý spúšťa hovory, sleduje ich naživo, usmerňuje agenta a odpovedá na jeho otázky pomocou verejného API.
V chatovacej aplikácii, ktorú váš tím už používa, môžete ovládať agenta. Správa spustí hovor. Hovor prebieha naživo vo vlákne. Odpoveď vo vlákne usmerní agenta. Keď agent potrebuje rozhodnutie, opýta sa vás tam a počka na vašu odpoveď.
ThunderPhone tento bot za vás neprevádzkuje. Vy (alebo váš agent na programovanie) vytvoríte malý server, ktorý prepojí vašu chatovaciu aplikáciu s verejným API. Táto stránka zobrazuje jednotlivé časti. Sú rovnaké pre Slack, Microsoft Teams, Discord alebo súkromnú webovú chatovaciu stránku; príklady používajú Slack.
Ako to funguje spolu
| Vy urobíte v chate toto | Váš bot zavolá | Čo sa stane |
|---|---|---|
| Pošlete „Zavolaj Comcastu a zisti odhad času odstránenia výpadku“ | POST /v1/call so správou ako context | Agent vytočí číslo. Váš bot otvorí vlákno pre hovor |
| Sledujete vlákno | Prijíma webhooky telephony.turn | Každý riadok, ktorý povie agent alebo druhá osoba, sa zobrazí vo vlákne |
| Odpoviete vo vlákne počas hovoru | POST /v1/calls/{call_id}/whisper | Agent dostane vašu poznámku súkromne a vykoná ju. Druhá osoba ju nikdy nepočuje |
| Odpoviete na otázku agenta | Váš koncový bod nástroja vráti vašu odpoveď alebo ju doručí neskôr prostredníctvom POST /v1/calls/{call_id}/tool-results | Agent s ňou pokračuje v hovore; v režime čakania druhá osoba medzitým počuje hudbu počas čakania |
| Prečítate si výsledok | Prijíma telephony.complete | Váš bot zverejní súhrn a výsledok |
Váš bot uchováva jedno mapovanie: ktoré chatové vlákno patrí ku ktorému call_id.
Skôr než začnete
- Kľúč API, uložený na vašom serveri, nikdy nie v prehliadači ani v chate. Vytvorte ho v časti Nastavenia organizácie → Kľúče (pozrite si Kľúče).
- Číslo s povolenými odchádzajúcimi hovormi a agent pre hovory. Správa
sa stane
contextpre konkrétny hovor, takže jeden všeobecný agent spracuje každú úlohu. - Server, ktorý môže prijímať webhooky, napríklad Railway, Fly.io, Render alebo váš vlastný hostiteľ.
- Koncový bod webhooku smerujúci na tento server a prihlásený na odber
telephony.turnatelephony.complete. Udalosti turn sa odosielajú iba na koncové body, ktoré ich uvádzajú. Pozrite si Webhooky. Udalosti turn vyžadujú zapnuté nahrávanie hovorov agenta asummaryna konci hovoru vyžaduje nastavenie agenta Generovať súhrn hovoru; bez nich zostanú tieto polia prázdne. - Vaša vlastná chatovacia aplikácia. Pre Slack vytvorte aplikáciu vo svojom pracovnom priestore na api.slack.com/apps.
1. Spustite hovor zo správy
Keď váš bot prijme správu (priamu správu alebo @zmienku),
okamžite potvrďte požiadavku Slacku (Slack opakuje všetko, čo nie je
potvrdené do 3 sekúnd), a zvyšok spracujte na pozadí. Overte,
že odosielateľ je oprávnený uskutočňovať hovory, potom spustite hovor so
správou ako 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"
}'Uložte vrátené call_id k vláknu Slacku (channel spolu s
ts správy) a odpovedzte vo vlákne („Volám…“). Vytvorte
idempotency_key z kanála a ts správy (ts je jedinečné
iba v rámci svojho kanála), aby opakovaná udalosť Slacku nespustila druhý
hovor. Ak požiadavka uvádza osobu namiesto čísla, váš bot najprv vyhľadá
jej číslo. ThunderPhone vytáča iba to_number, ktoré odošlete.
2. Sledujte hovor vo vlákne
Každý webhook telephony.turn obsahuje call_id, hovoriaceho (role:
assistant pre agenta, user pre druhú osobu), text a
position ťahu. Vyhľadajte vlákno podľa call_id a
odošlite riadok.
- Overte každý webhook pred spracovaním. Pozrite si Overenie podpisov webhookov.
- Odstraňujte duplicity podľa
event_idobálky a zoraďte podľaposition. Doručenie prebieha aspoň raz a ťahy môžu prísť v nesprávnom poradí. - Zoskupujte riadky, ak by rušný hovor zahltil vlákno; odosielanie každých niekoľko sekúnd sa číta lepšie než jedna správa na riadok.
Keď príde telephony.complete, odošlite spôsob ukončenia hovoru (jeho status
a end_reason), summary a všetky extrahované údaje, potom
vlákno uzavrite. Polia nájdete v časti Dokončenie hovoru.
3. Usmerňujte hovor z vlákna
Keď niekto odpovie vo vlákne aktívneho hovoru, odošlite odpoveď ako šepot, pokiaľ agent nečaká na odpoveď na otázku (krok 4); v takom prípade je odpoveď odpoveďou na otázku:
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 ho počuje súkromne a zapracuje ho do svojho nasledujúceho ťahu; druhá
osoba samotný šepot nikdy nepočuje. Šepot má 1 až 1000 znakov. Kód
409 znamená, že hovor už nie je aktívny: oznámte vo vlákne, že hovor sa skončil.
4. Nechajte agenta opýtať sa vás
Poskytnite agentovi nástroj, napríklad ask_owner s jedným parametrom
question, ktorý volá váš server. Vytvorte ho ako
pripojenie API a prepojte ho s agentom.
Každá požiadavka nástroja obsahuje hovor v hlavičke X-ThunderPhone-Call-ID.
Existujú tri spôsoby, ako získať odpoveď späť.
Podržte hovor (až 10 minút). Nastavte nástroj do režimu podržania: spec.wait_mode
"hold" a spec.timeout až na 600 sekúnd (bez časového limitu trvá podržanie
20 sekúnd) prostredníctvom
API (editor na ovládacom paneli
ešte nemá ani jedno pole). Váš endpoint odošle otázku do vlákna hovoru a ihneď odpovie
výsledkom so stavom čakania:
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}Druhá strana počuje jednu vetu od agenta a potom hudbu počas podržania. V
telefónnom menu alebo hlasovej schránke agent namiesto toho používa hovorené aktualizácie a
agent s plným duplexom hovor nepodrží: odpoveď so stavom čakania dostane ako výsledok. Keď
odpoveď dorazí do vlákna, odošlite ju pomocou
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."}}'Hudba postupne stíchne a agent pokračuje s vašou odpoveďou. Ak nikto
neodpovie pred uplynutím timeout, agent dostane informáciu, že odpoveď neprišla, a ponúkne
druhej strane ďalšie kroky. Kým je otázka pre hovor nevybavená, nasledujúca
odpoveď v jeho vlákne ju zodpovie: odošlite ju ako výsledok nástroja a
neodosielajte ju zároveň ako šepot (šepot sa k agentovi dostane až po
vrátení výsledku nástroja). Pozrite si
Dlhé čakania.
Počkajte v požiadavke (až 3 minúty). Váš endpoint odošle otázku,
počíta na odpoveď a vráti ju, napríklad {"answer": "Yes, book Tuesday at 10."}.
Nastavte spec.timeout nástroja prostredníctvom API až na 180 sekúnd (predvolená
hodnota je 20). Nastavte vlastný časový limit endpointu o niekoľko sekúnd kratší
(napríklad 170 sekúnd), aby pri neodpovedaní stále vrátil
niečo, s čím môže agent pracovať, napríklad
{"answer": null, "note": "No reply yet. Offer to take a message."}. Nástroj,
ktorý dosiahne svoj timeout, sa k agentovi dostane ako chyba a váš hostiteľ musí
požiadavku držať otvorenú tak dlho. Kým čaká, agent druhej strane povie,
že to overuje, približne po 12 sekundách povie, že na tom stále pracuje, a
potom poskytne krátku aktualizáciu približne každých 15 sekúnd. Režim podržania funguje
aj tu: nastavte spec.wait_mode na "hold" a druhá strana namiesto
aktualizácií počuje hudbu.
Odpovedzte šepotom. Váš endpoint odošle otázku a ihneď sa vráti,
napríklad {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}.
Keď odpoveď dorazí, odošlite ju ako šepot (krok 3) a agent
na ňu ihneď zareaguje. Použite to pri odpovediach, ktoré môžu trvať dlhšie než
10 minút. Hovor nie je podržaný: vaša výzva by mala agentovi povedať,
čo má zatiaľ robiť, napríklad robiť druhej strane spoločnosť alebo ponúknuť,
že jej zavoláte späť.
V každom prípade v pokyne agenta uveďte, kedy má nástroj použiť a čo má povedať druhej strane počas čakania:
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, s ktorými treba počítať
- Váš endpoint musí odpovedať v rámci hodnoty
timeoutnástroja, najneskôr do 180 sekúnd. Nástroj v režime podržania môže ponechať hovor podržaný až 600 sekúnd s čakajúcim výsledkom. - Kým nástroj čaká, agent neodpovedá druhej osobe. V režime podržania počuje hudbu; inak krátke hovorené aktualizácie.
- Šepot môže mať najviac 1000 znakov.
- Doručenie
telephony.turnprebieha aspoň raz a môže byť mimo poradia.
Bezpečnostný kontrolný zoznam
- Uchovávajte kľúč API na svojom serveri.
- Overujte podpisy ThunderPhone vo webhookoch a požiadavkách nástrojov a
podpisové tajomstvo Slacku v požiadavkách Slacku. Dva podpisy ThunderPhone
používajú odlišné tajomstvá: doručenia webhookov používajú vlastné tajomstvo
endpointu webhooku a požiadavky nástrojov používajú tajomstvo webhooku vašej
organizácie z
GET /v1/webhook. - Rozhodnite, kto môže začať hovory: pred uskutočnením hovoru skontrolujte ID používateľa Slacku.
- Odchádzajúce hovory sa riadia rovnakými pravidlami ako všetky ostatné. Pozrite si Zákony o odchádzajúcich hovoroch.
Vytvorte to pomocou programovacieho agenta
Naveďte svojho programovacieho agenta na server MCP dokumentácie a na túto stránku a požiadajte ho o „Slack bota pre môjho agenta ThunderPhone, ktorý sa riadi týmto návodom“. Zeus, asistent v aplikácii ThunderPhone, môže nastaviť stranu agenta (endpoint webhooku, nástroj a riadky výzvy) a napísať v chate počiatočný kód pre bota.