ThunderPhone v3 on nüüd saadaval.Iseteenindusena alates 2 senti/min.Loe uudist

Developer cookbook

Halda kõnesid Slackist või vestlusrakendusest

Loo oma Slacki, Teamsi või veebivestluse bot, mis algatab kõnesid, jälgib neid reaalajas, suunab häälagenti ja vastab selle küsimustele avaliku API abil.

Saad juhtida häälagenti vestlusrakendusest, mida sinu meeskond juba kasutab. Sõnum alustab kõnet. Kõne kulgeb reaalajas lõimes. Lõimes antud vastus suunab häälagenti. Kui häälagent vajab otsust, küsib ta seda seal ja ootab sinu vastust.

ThunderPhone ei majuta seda robotit sinu eest. Sina (või sinu kodeerimisagent) ehitad väikese serveri, mis ühendab sinu vestlusrakenduse avaliku API-ga. Sellel lehel on näidatud vajalikud osad. Need on samad Slacki, Microsoft Teamsi, Discordi või privaatse veebivestluslehe puhul; näited kasutavad Slacki.

Kuidas see kokku sobib

Teed seda vestlusesSinu robot kutsubMis juhtub
Saada „Helista Comcastile ja küsi katkestuse eeldatavat lõppaega”POST /v1/call, kus sõnum on contextHäälagent valib numbri. Sinu robot avab kõne jaoks lõime
Jälgi lõimeVõtab vastu telephony.turn veebikonksudIga rida, mille häälagent või teine osapool ütleb, ilmub lõimesse
Vasta kõne ajal lõimesPOST /v1/calls/{call_id}/whisperHäälagent saab sinu märkuse privaatselt kätte ja tegutseb selle järgi. Teine osapool ei kuule seda kunagi
Vasta häälagendi küsimuseleSinu tööriista lõpp-punkt tagastab sinu vastuse või edastab selle hiljem käsuga POST /v1/calls/{call_id}/tool-resultsHäälagent jätkab sellega kõnet; ootelrežiimis kuuleb teine osapool samal ajal ootelmuusikat
Loe tulemustVõtab vastu telephony.completeSinu robot postitab kokkuvõtte ja tulemuse

Sinu robot hoiab üht vastendust: milline vestluslõim kuulub millisele call_id-le.

Enne alustamist

  • API-võti, mida hoitakse sinu serveris, mitte kunagi brauseris ega vestluses. Loo see jaotises Integratsioonid → API-võtmed (vt Serveri API-võtme loomine).
  • Väljuvate kõnede toega number ja häälagent kõnede jaoks. Sõnum muutub kõnepõhiseks context-iks, seega üks üldine häälagent haldab kõiki ülesandeid.
  • Server, mis saab vastu võtta veebikonksusid, näiteks Railway, Fly.io, Render või sinu enda host.
  • Veebikonksu lõpp-punkt, mis osutab sellele serverile ja on tellitud sündmustele telephony.turn ja telephony.complete. Kõnevooru sündmused saadetakse ainult neid loetlevatele lõpp-punktidele. Vt Veebikonksud. Kõnevooru sündmused nõuavad, et agendi kõnesalvestus oleks sisse lülitatud, ning kõne lõpu summary nõuab agendi sätet Loo kõne kokkuvõte; ilma nendeta jäävad need väljad tühjaks.
  • Sinu enda vestlusrakendus. Slacki jaoks loo oma tööruumis rakendus aadressil api.slack.com/apps.

1. Alusta kõnet sõnumist

Kui sinu bot saab sõnumi (otsesõnumi või @mainimise), kinnita Slacki päring kohe (Slack proovib uuesti kõike, mida ei kinnitata 3 sekundi jooksul), ja tee ülejäänu taustal. Kontrolli, et saatjal on õigus kõnesid teha, seejärel alusta kõnet, kasutades sõnumit context-ina:

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"
  }'

Salvesta tagastatud call_id Slacki lõime juurde (channel koos sõnumi ts-iga) ja vasta lõimes ("Helistan…"). Koosta idempotency_key kanali ja sõnumi ts-i põhjal (ts on kordumatu ainult oma kanalis), et uuesti proovitud Slacki sündmus ei algataks teist kõnet. Kui päringus on numbri asemel isiku nimi, otsib sinu bot numbri esmalt üles. ThunderPhone valib ainult sinu saadetud to_number-i.

2. Jälgi kõnet lõimes

Iga telephony.turn webhook sisaldab call_id-d, kõnelejat (role: assistant agendi jaoks, user teise isiku jaoks), text-i ja käigu position-i. Leia lõim call_id järgi ja postita rida.

  • Kontrolli iga webhooki enne selle põhjal tegutsemist. Vaata Webhooki allkirjade kontrollimine.
  • Eemalda duplikaadid ümbrise event_id alusel ja järjestage need position järgi. Edastus toimub vähemalt üks kord ning käigud võivad saabuda vales järjekorras.
  • Koonda read rühmadeks, kui aktiivne kõne ujutaks lõime üle; iga mõne sekundi järel postitamine on loetavam kui üks sõnum rea kohta.

Kui saabub telephony.complete, postita, kuidas kõne lõppes (selle status ja end_reason), summary ning kõik eraldatud andmed, ja sulge lõim. Väljade kohta vaata Kõne lõpetamine.

3. Suuna kõnet lõimest

Kui keegi vastab aktiivse kõne lõimes, saada vastus sosinana, välja arvatud juhul, kui agent ootab küsimusele vastust (samm 4), mil vastus on vastus küsimusele:

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 kuuleb seda privaatselt ja põimib selle oma järgmisse käiku; teine isik ei kuule sosinat kunagi. Sosin võib olla 1 kuni 1000 tähemärki. 409 tähendab, et kõne ei ole enam aktiivne: teavita lõime, et kõne on lõppenud.

4. Lase häälagendil sinult küsida

Anna häälagendile tööriist, näiteks ask_owner ühe parameetriga question, mis kutsub sinu serverit. Loo see API-ühendusena ja seo häälagendiga. Iga tööriistapäring kannab kõnet päises X-ThunderPhone-Call-ID.

Vastuse tagasisaamiseks on kolm võimalust.

Pane kõne ootele (kuni 10 minutiks). Määra tööriist ooterežiimile: spec.wait_mode "hold" ja spec.timeout kuni 600 sekundini (ilma ajalõputa kestab ootel hoidmine 20 sekundit), kasutades API-t, või palu Zeusil need määrata (rakenduse redaktoritel pole kumbagi välja veel). Sinu lõpp-punkt postitab küsimuse kõne lõime ja vastab kohe ootel oleva tulemusega:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

Teine osapool kuuleb häälagendilt üht lauset ja seejärel ootelmuusikat. Telefonimenüüs või kõnepostis kasutab häälagent selle asemel suulisi teavitusi ning täisdupleksne häälagent ei pane kõnet ootele: ta saab ootel vastuse tulemusena. Kui vastus jõuab lõime, edasta see kaudu 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."}}'

Muusika vaibub ja häälagent jätkab sinu vastusega. Kui keegi ei vasta enne timeout-i, öeldakse häälagendile, et vastust ei saabunud, ning ta pakub teisele osapoolele järgmisi samme. Kui kõne küsimus on ootel, vastab sellele selle lõime järgmine vastus: edasta see tööriista tulemusena ja ära saada seda lisaks sosinsõnumina (sosinsõnum jõuab häälagendini alles pärast tööriista tagastamist). Vaata Pikki ootamisi.

Oota päringus (kuni 3 minutit). Sinu lõpp-punkt postitab küsimuse, ootab vastust ja tagastab selle, näiteks {"answer": "Yes, book Tuesday at 10."}. Määra tööriista spec.timeout API kaudu kuni 180 sekundile (vaikimisi on 20). Määra oma lõpp-punktile mõne sekundi võrra lühem ajalimiit (näiteks 170 sekundit), et juhul, kui keegi ei vasta, tagastaks see siiski midagi, mille põhjal häälagent saab tegutseda, näiteks {"answer": null, "note": "No reply yet. Offer to take a message."}. Tööriist, mis jõuab oma timeout-ini, jõuab häälagendini veana ning sinu server peab hoidma päringut nii kaua avatuna. Ootamise ajal ütleb häälagent teisele osapoolele, et ta kontrollib, teatab umbes 12 sekundi pärast, et töö jätkub, ning annab seejärel lühikese teavituse umbes iga 15 sekundi järel. Ka siin toimib ooteležiim: määra spec.wait_mode väärtuseks "hold" ja teine osapool kuuleb teavituste asemel muusikat.

Vasta sosinsõnumiga. Sinu lõpp-punkt postitab küsimuse ja tagastab kohe, näiteks {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Kui vastus saabub, saada see sosinsõnumina (3. samm) ja häälagent vastab sellele kohe. Kasuta seda vastuste jaoks, mis võivad võtta kauem kui 10 minutit. Kõnet ei panda ootele: sinu juhis peaks ütlema häälagendile, mida vahepeal teha, näiteks teisele osapoolele seltsi pakkuda või pakkuda talle tagasi helistamist.

Igal juhul ütle häälagendi juhises, millal tööriista kasutada ja mida teisele osapoolele ootamise ajal öelda:

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.

Planeeritavad piirangud

  • Sinu lõpp-punkt peab vastama tööriista timeout-i jooksul, maksimaalselt 180 sekundiga. Ootel režiimis tööriist võib hoida kõnet ootel kuni 600 sekundit, kui tulemus on ootel.
  • Kui tööriist ootab, ei vasta agent teisele osapoolele. Ootel režiimis kuuleb ta muusikat; muul juhul lühikesi suulisi olekuuuendusi.
  • Sosistus võib olla kuni 1000 tähemärki.
  • telephony.turn edastus toimub vähemalt üks kord ja võib jõuda kohale vales järjekorras.

Turvalisuse kontrollnimekiri

  • Hoia API-võtit oma serveris.
  • Kontrolli ThunderPhone'i allkirju veebikonksudel ja tööriistataotlustel ning Slacki allkirjastamissaladust Slacki taotlustel. Kahel ThunderPhone'i allkirjal on erinevad saladused: veebikonksu edastused kasutavad veebikonksu lõpp-punkti enda saladust ja tööriistataotlused sinu organisatsiooni veebikonksu saladust, mille saad GET /v1/webhook-ist.
  • Otsusta, kes võib kõnesid alustada: kontrolli enne kõne tegemist Slacki kasutaja ID-d.
  • Väljuvatele kõnedele kehtivad samad reeglid nagu kõigile teistele. Vaata väljuvate kõnede seadusi.

Loo see programmeerimisagendiga

Suuna oma programmeerimisagent dokumentatsiooni MCP-serveri ja selle lehe juurde ning palu luua „Slacki bott minu ThunderPhone'i agendile, mis järgib seda juhendit”. ThunderPhone'i rakenduse abiline Zeus saab seadistada agendi poole (veebikonksu lõpp-punkti, tööriista ja viiba read) ning kirjutada vestluses botile algkoodi.