ThunderPhone v3 jau veikia.Viską atlikite savarankiškai – nuo 2 ct/min.Skaityti pranešimą

Developer cookbook

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 pokalbyjeKą iškviečia jūsų botasKas nutinka
Siunčiate „Paskambinkite Comcast ir sužinokite numatomą gedimo pašalinimo laiką“POST /v1/call, o žinutė perduodama kaip contextAgentas surenka numerį. Jūsų botas atidaro skambučio giją
Stebite gijąGauna telephony.turn žiniatinklio kabliukusKiekviena agento ar kito asmens pasakyta eilutė rodoma gijoje
Atsakote gijoje skambučio metuPOST /v1/calls/{call_id}/whisperAgentas 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-resultsAgentas tęsia skambutį jį naudodamas; sulaikymo režimu kitas asmuo tuo metu girdi laukimo muziką
Perskaitote rezultatąGauna telephony.completeJū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.turn bei telephony.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 pabaigos summary bū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_id ir rikiuokite pagal position. 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.turn pristatomas 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.