ThunderPhone v3 je zdaj na voljo.Začnite sami, že od 2 ¢/min.Preberite obvestilo

Developer cookbook

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 klepetuVaš bot pokličeKaj se zgodi
Pošljete »Pokliči Comcast in pridobi predvideni čas odprave izpada«POST /v1/call s sporočilom kot contextAgent pokliče. Vaš bot odpre nit za klic
Spremljate nitPrejema spletne klice telephony.turnVsaka vrstica, ki jo izreče agent ali druga oseba, se prikaže v niti
Med klicem odgovorite v nitiPOST /v1/calls/{call_id}/whisperAgent zasebno prejme vašo opombo in ukrepa po njej. Druga oseba je nikoli ne sliši
Odgovorite na vprašanje agentaVaša končna točka orodja vrne vaš odgovor ali ga pozneje dostavi z POST /v1/calls/{call_id}/tool-resultsAgent nadaljuje klic z njim; v načinu čakanja druga oseba medtem sliši glasbo za čakanje
Preberete rezultatPrejema spletne klice telephony.completeVaš 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 context za 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.turn in telephony.complete. Dogodki obratov so poslani le na končne točke, ki jih navajajo. Glejte Spletni klici. Dogodki obratov zahtevajo vklopljeno snemanje klicev agenta, za summary ob 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_id ovojnice in razvrstite po position. 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 timeout orodja, 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.turn se 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.