Open in
Vykdykite skambučius iš Slack arba pokalbių programos
Sukurkite savo Slack, Teams arba žiniatinklio pokalbių robotą, kuris inicijuoja skambučius, stebi juos tiesiogiai, nukreipia agentą ir atsako į jo klausimus, naudodamas viešąją API.
Galite valdyti agentą iš pokalbių programos, kurią jūsų komanda jau naudoja. Žinutė pradeda skambutį. Skambutis vyksta tiesiogiai gijoje. Atsakymas gijoje nukreipia agentą. Kai agentui reikia sprendimo, jis jo jūsų ten paklausia ir laukia jūsų atsakymo.
ThunderPhone šio boto jums neteikia. Jūs (arba jūsų programavimo agentas) sukuriate nedidelį serverį, kuris sujungia jūsų pokalbių programą su viešąja API. Šiame puslapyje rodomos sudedamosios dalys. Jos tokios pačios Slack, Microsoft Teams, Discord ar privačiam žiniatinklio pokalbių puslapiui; pavyzdžiuose naudojamas Slack.
Kaip tai veikia kartu
| Ką darote pokalbyje | Ką iškviečia jūsų botas | Kas nutinka |
|---|---|---|
| Siunčiate „Paskambinkite Comcast ir sužinokite numatomą gedimo pašalinimo laiką“ | POST /v1/call, o žinutė perduodama kaip context | Agentas surenka numerį. Jūsų botas atidaro skambučio giją |
| Stebite giją | Gauna telephony.turn žiniatinklio kabliukus | Kiekviena agento ar kito asmens pasakyta eilutė rodoma gijoje |
| Atsakote gijoje skambučio metu | POST /v1/calls/{call_id}/whisper | Agentas privačiai gauna jūsų pastabą ir pagal ją veikia. Kitas asmuo jos niekada negirdi |
| Atsakote į agento klausimą | Jūsų įrankio galinis taškas grąžina jūsų atsakymą arba pateikia jį vėliau per POST /v1/calls/{call_id}/tool-results | Agentas tęsia skambutį jį naudodamas; sulaikymo režimu kitas asmuo tuo metu girdi laukimo muziką |
| Perskaitote rezultatą | Gauna telephony.complete | Jūsų botas paskelbia suvestinę ir rezultatą |
Jūsų botas saugo vieną susiejimą: kuri pokalbio gija priklauso kuriam call_id.
Prieš pradėdami
- API raktas, saugomas jūsų serveryje ir niekada naršyklėje ar pokalbyje. Sukurkite jį skiltyje Organizacijos nustatymai → Raktai (žr. Raktai).
- Numeris, kuriuo galima skambinti, ir agentas skambučiams. Žinutė
tampa konkretaus skambučio
context, todėl vienas bendras agentas gali atlikti kiekvieną užduotį. - Serveris, galintis priimti žiniatinklio kabliukus, pavyzdžiui, Railway, Fly.io, Render arba jūsų pačių priegloba.
- Žiniatinklio kabliuko galinis taškas, nukreiptas į tą serverį ir prenumeruojantis
telephony.turnbeitelephony.complete. Pokyčio įvykiai siunčiami tik į galinius taškus, kuriuose jie nurodyti. Žr. Žiniatinklio kabliukai. Pokyčio įvykiams būtinas įjungtas agento skambučio įrašymas, o skambučio pabaigossummarybūtinas agento nustatymas Generuoti skambučio suvestinę; be jų šie laukai lieka tušti. - Jūsų pokalbių programa. Jei naudojate Slack, sukurkite programą savo darbo erdvėje adresu api.slack.com/apps.
1. Pradėkite skambutį iš žinutės
Kai jūsų robotas gauna žinutę (tiesioginę žinutę arba @paminėjimą),
nedelsdami patvirtinkite Slack užklausą (Slack pakartoja viską, kas
nepatvirtinama per 3 sekundes), o visa kita atlikite fone. Patikrinkite,
ar siuntėjui leidžiama skambinti, tada pradėkite skambutį, naudodami žinutę kaip
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"
}'Išsaugokite grąžintą call_id kartu su Slack gija (channel ir
žinutės ts) ir atsakykite gijoje („Skambinama…“). Sudarykite
idempotency_key iš kanalo ir žinutės ts (ts yra unikalus
tik savo kanale), kad pakartotinai gautas Slack įvykis nepradėtų antro
skambučio. Jei užklausoje nurodytas asmuo, o ne numeris, jūsų robotas
pirmiausia suranda numerį. ThunderPhone skambina tik jūsų siunčiamu to_number.
2. Stebėkite skambutį gijoje
Kiekviename telephony.turn žiniatinklio kabliuke pateikiami call_id,
kalbėtojas (role: assistant agentui, user kitam asmeniui), text ir
ėjimo position. Suraskite giją pagal call_id ir
paskelbkite eilutę.
- Patikrinkite kiekvieną žiniatinklio kabliuką prieš imdamiesi veiksmų. Žr. Žiniatinklio kabliukų parašų tikrinimas.
- Pašalinkite dublikatus pagal įvykio apvalkalo
event_idir rikiuokite pagalposition. Pristatymas vyksta bent kartą, o ėjimai gali būti gauti ne eilės tvarka. - Grupuokite eilutes, jei intensyvus skambutis užlietų giją; skelbti kas kelias sekundes yra patogiau skaityti nei po vieną žinutę kiekvienai eilutei.
Kai gaunamas telephony.complete, paskelbkite, kaip baigėsi skambutis (jo status
ir end_reason), summary bei visus išgautus duomenis, tada užbaikite
giją. Laukų sąrašą žr. Skambučio užbaigimas.
3. Valdykite skambutį iš gijos
Kai kas nors atsako aktyvaus skambučio gijoje, siųskite atsakymą kaip šnabždesį, nebent agentas laukia atsakymo į klausimą (4 veiksmas); tokiu atveju atsakymas yra atsakymas į klausimą:
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."}'Agentas jį girdi privačiai ir įtraukia į kitą savo ėjimą; kitas
asmuo niekada negirdi paties šnabždesio. Šnabždesį sudaro nuo 1 iki 1000 simbolių. Kodas
409 reiškia, kad skambutis nebėra aktyvus: praneškite gijoje, kad skambutis baigėsi.
4. Leiskite agentui jūsų paklausti
Suteikite agentui įrankį, pavyzdžiui, ask_owner su vienu question
parametru, kuris iškviečia jūsų serverį. Sukurkite jį kaip
API ryšį ir susiekite su agentu.
Kiekvienoje įrankio užklausoje skambutis perduodamas X-ThunderPhone-Call-ID antraštėje.
Atsakymą galite grąžinti trimis būdais.
Sulaikykite skambutį (iki 10 minučių). Nustatykite įrankio sulaikymo režimą: spec.wait_mode
"hold" ir spec.timeout iki 600 sekundžių (be skirtojo laiko sulaikymas
trunka 20 sekundžių), naudodami
API (valdymo skydelio
redagavimo priemonėje kol kas nėra nė vieno iš šių laukų). Jūsų galinis taškas paskelbia klausimą skambučio gijoje ir iš karto atsako
laukiančiu rezultatu:
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}Kitas asmuo išgirsta vieną agento sakinį, tada laukimo muziką. Telefoniniame
meniu ar balso pašte agentas vietoj to pateikia sakytinius pranešimus, o
viso duplekso agentas nesulaiko: jis gauna laukiantį atsakymą kaip rezultatą. Kai
atsakymas gaunamas gijoje, pateikite jį naudodami
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."}}'Muzika nutyla, o agentas tęsia pokalbį naudodamas jūsų atsakymą. Jei niekas
neatsako iki timeout, agentui pranešama, kad atsakymas nebuvo gautas, ir jis pasiūlo
kitam asmeniui tolesnius veiksmus. Kol skambučiui laukiamas klausimo atsakymas,
kitas atsakymas jo gijoje į jį atsako: pateikite jį kaip įrankio rezultatą ir
nesiųskite jo papildomai kaip kuždesio (kuždesys agentą pasiekia tik grįžus
įrankio rezultatui). Žr.
Ilgas laukimas.
Laukite užklausoje (iki 3 minučių). Jūsų galinis taškas paskelbia klausimą,
laukia atsakymo ir jį grąžina, pavyzdžiui, {"answer": "Yes, book Tuesday at 10."}.
Nustatykite įrankio spec.timeout per API iki 180 sekundžių (numatytoji reikšmė
yra 20). Savo galiniam taškui nustatykite keliomis sekundėmis trumpesnį
terminą (pavyzdžiui, 170 sekundžių), kad niekam neatsakius jis vis tiek grąžintų
kažką, pagal ką agentas galėtų veikti, pavyzdžiui,
{"answer": null, "note": "No reply yet. Offer to take a message."}. Įrankis,
pasiekęs savo timeout, agentą pasiekia kaip klaida, o jūsų priegloba turi
išlaikyti užklausą atidarytą tiek laiko. Kol laukia, agentas kitam asmeniui
pasako, kad tikrina, maždaug po 12 sekundžių praneša, kad vis dar dirba, o
vėliau maždaug kas 15 sekundžių pateikia trumpą naujinį. Čia taip pat veikia
sulaikymo režimas: nustatykite spec.wait_mode į "hold", ir kitas asmuo
vietoj naujinių girdės muziką.
Atsakykite kuždesiu. Jūsų galinis taškas paskelbia klausimą ir iš karto grąžina
atsakymą, pavyzdžiui, {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}.
Kai gaunamas atsakymas, nusiųskite jį kaip kuždesį (3 veiksmas), ir agentas
į jį iš karto atsakys. Naudokite tai atsakymams, kurie gali užtrukti ilgiau nei
10 minučių. Skambutis nesulaikomas: jūsų raginime agentui turėtų būti nurodyta,
ką daryti tuo metu, pavyzdžiui, palaikyti asmeniui draugiją arba pasiūlyti
jam perskambinti.
Kiekvienu atveju agento raginime nurodykite, kada naudoti įrankį ir ką sakyti kitam asmeniui, kol laukiama:
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.Ribos, į kurias reikia atsižvelgti
- Jūsų galinis taškas turi atsakyti per įrankio
timeout, ne vėliau kaip per 180 sekundžių. Sulaikymo režimu veikiantis įrankis gali laikyti skambutį sulaikytą iki 600 sekundžių, kol laukiamas rezultatas. - Kol įrankis laukia, agentas neatsako kitam asmeniui. Sulaikymo režimu jis girdi muziką; kitu atveju – trumpus sakytinius atnaujinimus.
- Šnabždesį gali sudaryti ne daugiau kaip 1000 simbolių.
telephony.turnpristatomas bent kartą ir gali būti pristatytas ne eilės tvarka.
Saugumo kontrolinis sąrašas
- Laikykite API raktą savo serveryje.
- Patikrinkite ThunderPhone parašus žiniatinklio kabliukuose ir įrankių užklausose, taip pat
Slack pasirašymo paslaptį Slack užklausose. Du ThunderPhone
parašai naudoja skirtingas paslaptis: žiniatinklio kabliukų pristatymai naudoja paties
žiniatinklio kabliuko galinio taško paslaptį, o įrankių užklausos naudoja jūsų organizacijos žiniatinklio
kabliuko paslaptį iš
GET /v1/webhook. - Nuspręskite, kas gali pradėti skambučius: prieš inicijuodami skambutį patikrinkite Slack naudotojo ID.
- Išeinantiems skambučiams taikomos tos pačios taisyklės kaip ir bet kuriems kitiems. Žr. Išeinančių skambučių įstatymai.
Sukurkite tai su programavimo agentu
Nukreipkite savo programavimo agentą į dokumentacijos MCP serverį ir į šį puslapį bei paprašykite „Slack boto mano ThunderPhone agentui, kuris laikosi šio vadovo“. Zeus, ThunderPhone programėlės asistentas, gali nustatyti agento pusę (žiniatinklio kabliuko galinį tašką, įrankį ir raginimo eilutes) bei parašyti pradinį boto kodą pokalbyje.