Open in
Izvajajte klice iz Slacka ali aplikacije za klepet
Z javnim API-jem ustvarite lastnega bota za Slack, Teams ali spletni klepet, ki začenja klice, jim sledi v živo, usmerja agenta in odgovarja na njegova vprašanja.
Svojega agenta lahko upravljate iz aplikacije za klepet, ki jo vaša ekipa že uporablja. Sporočilo začne klic. Klic poteka v živo v niti. Odgovor v niti usmerja agenta. Ko agent potrebuje odločitev, vas zanjo vpraša tam in počaka na vaš odgovor.
ThunderPhone tega bota ne gosti namesto vas. Vi (ali vaš agent za programiranje) ustvarite majhen strežnik, ki vašo aplikacijo za klepet poveže z javnim API-jem. Ta stran prikazuje sestavne dele. Ti so enaki za Slack, Microsoft Teams, Discord ali zasebno spletno stran za klepet; primeri uporabljajo Slack.
Kako deluje skupaj
| To naredite v klepetu | Vaš bot pokliče | Kaj se zgodi |
|---|---|---|
| Pošljete »Pokliči Comcast in pridobi predvideni čas odprave izpada« | POST /v1/call s sporočilom kot context | Agent pokliče. Vaš bot odpre nit za klic |
| Spremljate nit | Prejema spletne klice telephony.turn | Vsaka vrstica, ki jo izreče agent ali druga oseba, se prikaže v niti |
| Med klicem odgovorite v niti | POST /v1/calls/{call_id}/whisper | Agent zasebno prejme vašo opombo in ukrepa po njej. Druga oseba je nikoli ne sliši |
| Odgovorite na vprašanje agenta | Vaša končna točka orodja vrne vaš odgovor ali ga pozneje dostavi z POST /v1/calls/{call_id}/tool-results | Agent nadaljuje klic z njim; v načinu čakanja druga oseba medtem sliši glasbo za čakanje |
| Preberete rezultat | Prejema spletne klice telephony.complete | Vaš bot objavi povzetek in izid |
Vaš bot vzdržuje eno preslikavo: katera nit klepeta pripada kateremu call_id.
Preden začnete
- Ključ API-ja, shranjen na vašem strežniku in nikoli v brskalniku ali klepetu. Ustvarite ga v razdelku Nastavitve organizacije → Ključi (glejte Ključi).
- Številka z omogočenimi odhodnimi klici in agent za klice. Sporočilo
postane
contextza posamezen klic, zato en splošen agent obravnava vsako nalogo. - Strežnik, ki lahko prejema spletne klice, na primer Railway, Fly.io, Render ali vaš lastni gostitelj.
- Končna točka za spletne klice, usmerjena na ta strežnik in naročena na
telephony.turnintelephony.complete. Dogodki obratov so poslani le na končne točke, ki jih navajajo. Glejte Spletni klici. Dogodki obratov zahtevajo vklopljeno snemanje klicev agenta, zasummaryob koncu klica pa je potrebna agentova nastavitev Ustvari povzetek klica; brez tega ta polja ostanejo prazna. - Vaša lastna aplikacija za klepet. Za Slack ustvarite aplikacijo v svojem delovnem prostoru na api.slack.com/apps.
1. Začnite klic iz sporočila
Ko vaš bot prejme sporočilo (neposredno sporočilo ali omembo z @),
takoj potrdite Slackovo zahtevo (Slack znova pošlje vse, kar ni
potrjeno v 3 sekundah), preostalo pa izvedite v ozadju. Preverite,
ali pošiljatelj sme opravljati klice, nato začnite klic s sporočilom kot
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"
}'Vrnjeni call_id shranite ob Slackovi niti (channel skupaj z
vrednostjo ts sporočila) in odgovorite v niti ("Kličem …"). Ustvarite
idempotency_key iz kanala in vrednosti ts sporočila (vrednost ts je
enolična samo znotraj svojega kanala), da ponovljeni Slackov dogodek ne
začne drugega klica. Če zahteva navaja osebo namesto številke, vaš bot
najprej poišče številko. ThunderPhone kliče samo številko to_number, ki jo pošljete.
2. Spremljajte klic v niti
Vsak spletni kavelj telephony.turn vsebuje call_id, govorca (role:
assistant za agenta, user za drugo osebo), text in
position poteze. Poiščite nit po call_id in
objavite vrstico.
- Preverite vsak spletni kavelj, preden ukrepate na njegovi podlagi. Glejte Preverjanje podpisov spletnih kavljev.
- Odstranite podvojitve po
event_idovojnice in razvrstite poposition. Dostava je vsaj enkratna, poteze pa lahko prispejo v napačnem vrstnem redu. - Združujte vrstice, če bi prometen klic preplavil nit; objavljanje vsakih nekaj sekund je bolj berljivo kot eno sporočilo na vrstico.
Ko prispe telephony.complete, objavite način zaključka klica (njegova
status in end_reason), summary ter vse pridobljene podatke in
zaključite nit. Za polja glejte Zaključek klica.
3. Usmerjajte klic iz niti
Ko nekdo odgovori v niti aktivnega klica, pošljite odgovor kot šepet, razen če agent čaka na odgovor na vprašanje (4. korak), v tem primeru je odgovor odgovor na vprašanje:
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 ga sliši zasebno in ga vključi v svojo naslednjo potezo; druga
oseba samega šepeta nikoli ne sliši. Šepet vsebuje od 1 do 1000 znakov. Koda
409 pomeni, da klic ni več aktiven: niti sporočite, da se je klic končal.
4. Omogočite agentu, da vas vpraša
Agentu dodelite orodje, na primer ask_owner z enim parametrom
question, ki pokliče vaš strežnik. Ustvarite ga kot
povezavo API in ga povežite z agentom.
Vsaka zahteva orodja vsebuje klic v glavi X-ThunderPhone-Call-ID.
Odgovor lahko vrnete na tri načine.
Zadržite klic (do 10 minut). Orodje nastavite na način zadržanja: spec.wait_mode
"hold" in spec.timeout do 600 sekund (brez časovne omejitve zadržanje
traja 20 sekund) prek
API-ja (urejevalnik na
nadzorni plošči še nima nobenega od teh polj). Vaša končna točka objavi vprašanje v nit klica in takoj
odgovori z rezultatom v čakanju:
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}Sogovornik sliši eno poved agenta, nato glasbo med zadržanjem. V
telefonskem meniju ali glasovni pošti agent namesto tega uporablja govorne posodobitve, agent s
polnim dupleksom pa klica ne zadrži: odgovor v čakanju prejme kot rezultat. Ko
odgovor prispe v nit, ga dostavite z
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."}}'Glasba postopoma utihne in agent nadaljuje z vašim odgovorom. Če nihče
ne odgovori pred timeout, agent izve, da odgovora ni prejel, in sogovorniku ponudi
naslednje korake. Dokler vprašanje čaka za klic, nanj odgovori naslednji
odgovor v njegovi niti: dostavite ga kot rezultat orodja in ga ne pošljite
še kot šepet (šepet doseže agenta šele po vrnitvi orodja). Glejte
Dolga čakanja.
Počakajte v zahtevi (do 3 minute). Vaša končna točka objavi vprašanje,
počaka na odgovor in ga vrne, na primer {"answer": "Yes, book Tuesday at 10."}.
Nastavite spec.timeout orodja prek API-ja, do 180 sekund (privzeta
vrednost je 20). Svoji končni točki določite lasten rok nekaj sekund krajši
(na primer 170 sekund), da tudi takrat, ko nihče ne odgovori, še vedno vrne
nekaj, na podlagi česar lahko agent ukrepa, na primer
{"answer": null, "note": "No reply yet. Offer to take a message."}. Orodje,
ki doseže timeout, agenta doseže kot napaka, vaš gostitelj pa mora zahtevo
obdržati odprto toliko časa. Med čakanjem agent sogovorniku pove, da preverja,
po približno 12 sekundah pove, da še vedno dela, nato pa približno vsakih 15 sekund
navede kratko posodobitev. Tudi tukaj deluje način zadržanja: nastavite spec.wait_mode
na "hold" in sogovornik namesto posodobitev sliši glasbo.
Odgovorite s šepetom. Vaša končna točka objavi vprašanje in se takoj vrne,
na primer {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}.
Ko odgovor prispe, ga pošljite kot šepet (3. korak), agent pa
se nanj takoj odzove. To uporabite za odgovore, ki lahko trajajo dlje kot
10 minut. Klic ni zadržan: vaš poziv mora
agentu povedati, kaj naj medtem počne, na primer naj sogovorniku dela družbo ali ponudi,
da ga pokliče nazaj.
V vsakem primeru v pozivu agenta navedite, kdaj naj uporabi orodje in kaj naj med čakanjem pove sogovorniku:
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.Omejitve, ki jih upoštevajte pri načrtovanju
- Vaša končna točka mora odgovoriti v okviru
timeoutorodja, največ v 180 sekundah. Orodje v načinu zadržanja lahko klic zadrži do 600 sekund ob čakajočem rezultatu. - Medtem ko orodje čaka, agent drugi osebi ne odgovarja. V načinu zadržanja sliši glasbo, sicer pa kratka glasovna obvestila.
- Šepet obsega največ 1000 znakov.
- Dostava
telephony.turnse izvede vsaj enkrat in je lahko neurejena.
Varnostni kontrolni seznam
- Ključ API hranite na svojem strežniku.
- Preverite podpise ThunderPhone v spletnih kaveljcih in zahtevah orodij ter
Slackovo podpisno skrivnost v Slackovih zahtevah. Podpisa ThunderPhone
uporabljata različni skrivnosti: dostave spletnih kavljev uporabljajo lastno skrivnost
končne točke spletnega kavlja, zahteve orodij pa skrivnost spletnega kavlja vaše organizacije
iz
GET /v1/webhook. - Določite, kdo lahko začne klice: pred vzpostavitvijo klica preverite ID uporabnika Slacka.
- Odhodni klici upoštevajo enaka pravila kot vsi drugi. Oglejte si Zakoni o odhodnih klicih.
Izdelajte ga s programerskim agentom
Svojega programerskega agenta usmerite na strežnik MCP za dokumentacijo in na to stran ter zahtevajte »bota Slack za mojega agenta ThunderPhone, ki upošteva ta vodnik«. Zeus, pomočnik v aplikaciji ThunderPhone, lahko nastavi stran agenta (končno točko spletnega kavlja, orodje in vrstice poziva) ter v klepetu napiše začetno kodo za bota.