ThunderPhone v3 on julkaistu.Ota käyttöön itse – alkaen 2 ¢/min.Lue lisää julkistuksesta

Developer cookbook

Soita puheluita Slackista tai chat-sovelluksesta

Rakenna oma Slack-, Teams- tai verkkokeskustelubotti, joka aloittaa puheluita, seuraa niitä reaaliajassa, ohjaa agenttia ja vastaa sen kysymyksiin julkisen API:n avulla.

Voit ohjata agenttia tiimisi jo käyttämästä chat-sovelluksesta. Viesti käynnistää puhelun. Puhelu etenee reaaliajassa keskusteluketjussa. Ketjuun lähetetty vastaus ohjaa agenttia. Kun agentti tarvitsee päätöksen, se kysyy sinulta siellä ja odottaa vastaustasi.

ThunderPhone ei isännöi tätä bottia puolestasi. Sinä (tai koodausagenttisi) rakennat pienen palvelimen, joka yhdistää chat-sovelluksesi julkiseen APIin. Tällä sivulla esitellään osat. Ne ovat samat Slackissa, Microsoft Teamsissa, Discordissa tai yksityisellä verkkokeskustelusivulla; esimerkeissä käytetään Slackia.

Näin se toimii yhdessä

Teet tämän chatissaBottisi kutsuuMitä tapahtuu
Lähetä "Soita Comcastille ja selvitä käyttökatkon arvioitu korjausaika"POST /v1/call, jossa viesti on contextAgentti soittaa. Bottisi avaa puhelulle keskusteluketjun
Seuraa keskusteluketjuaVastaanottaa telephony.turn-webhookejaJokainen agentin tai toisen henkilön sanoma rivi näkyy keskusteluketjussa
Vastaa keskusteluketjussa kesken puhelunPOST /v1/calls/{call_id}/whisperAgentti saa viestisi yksityisesti ja toimii sen mukaan. Toinen henkilö ei koskaan kuule sitä
Vastaa agentin kysymykseenOma työkalupäätepisteesi palauttaa vastauksesi tai toimittaa sen myöhemmin komennolla POST /v1/calls/{call_id}/tool-resultsAgentti jatkaa puhelua vastauksesi perusteella; pitotilassa toinen henkilö kuulee sillä välin odotusmusiikkia
Lue tulosVastaanottaa telephony.complete-webhookinBottisi julkaisee yhteenvedon ja lopputuloksen

Bottisi ylläpitää yhtä yhdistämistä: mikä chat-ketju kuuluu millekin call_id:lle.

Ennen aloittamista

  • API-avain, joka säilytetään palvelimellasi eikä koskaan selaimessa tai chatissa. Luo sellainen kohdassa Integraatiot → API-avaimet (katso Luo palvelimen API-avain).
  • Lähteviin puheluihin tarkoitettu numero ja agentti puheluita varten. Viestistä tulee puhelukohtainen context, joten yksi yleinen agentti hoitaa kaikki tehtävät.
  • Palvelin, joka voi vastaanottaa webhookeja, kuten Railway, Fly.io, Render tai oma palvelimesi.
  • Webhook-päätepiste, joka osoittaa kyseiseen palvelimeen ja on tilattu vastaanottamaan telephony.turn- ja telephony.complete-tapahtumia. Vuorotapahtumia lähetetään vain niitä luetteleviin päätepisteisiin. Katso Webhookit. Vuorotapahtumat edellyttävät, että agentin puhelutallennus on käytössä, ja puhelun lopun summary edellyttää agentin Luo puheluyhteenveto -asetusta; ilman niitä nämä kentät jäävät tyhjiksi.
  • Oma chat-sovelluksesi. Slackia varten luo sovellus työtilaasi osoitteessa api.slack.com/apps.

1. Aloita puhelu viestistä

Kun bottisi vastaanottaa viestin (suoran viestin tai @maininnan), vahvista Slackin pyyntö heti (Slack yrittää uudelleen kaikkea, mitä ei vahvisteta 3 sekunnin kuluessa), ja tee loput taustalla. Tarkista, että lähettäjällä on oikeus soittaa puheluita, ja aloita sitten puhelu viesti context-kenttänä:

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

Tallenna palautettu call_id Slack-säiettä varten (channel sekä viestin ts) ja vastaa säikeeseen ("Soitetaan…"). Muodosta idempotency_key kanavasta ja viestin ts-arvosta (ts on yksilöllinen vain omassa kanavassaan), jotta uudelleen yritetty Slack-tapahtuma ei aloita toista puhelua. Jos pyynnössä mainitaan henkilö numeron sijaan, bottisi hakee numeron ensin. ThunderPhone soittaa vain lähettämääsi to_number-numeroon.

2. Seuraa puhelua säikeessä

Jokainen telephony.turn-webhook sisältää call_id-tunnisteen, puhujan (role: assistant agentille, user toiselle henkilölle), text-tekstin sekä vuoron position-sijainnin. Hae säie call_id-tunnisteella ja lähetä rivi siihen.

  • Vahvista jokainen webhook ennen kuin toimit sen perusteella. Katso Vahvista webhook-allekirjoitukset.
  • Poista kaksoiskappaleet kirjekuoren event_id-tunnisteen perusteella ja järjestä position-arvon mukaan. Toimitus tapahtuu vähintään kerran, ja vuorot voivat saapua väärässä järjestyksessä.
  • Lähetä rivejä erissä, jos kiireinen puhelu täyttäisi säikeen; muutaman sekunnin välein julkaiseminen on luettavampaa kuin yksi viesti riviä kohden.

Kun telephony.complete saapuu, julkaise puhelun päättymistapa (sen status ja end_reason), summary sekä kaikki poimitut tiedot ja päätä säie. Katso kentät kohdasta Puhelu valmis.

3. Ohjaa puhelua säikeestä

Kun joku vastaa käynnissä olevan puhelun säikeeseen, lähetä vastaus kuiskauksena, ellei agentti odota vastausta kysymykseen (vaihe 4), jolloin vastaus on vastaus kysymykseen:

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

Agentti kuulee sen yksityisesti ja sisällyttää sen seuraavaan vuoroonsa; toinen henkilö ei koskaan kuule itse kuiskausta. Kuiskaus on 1–1000 merkkiä pitkä. Jos saat 409-vastauksen, puhelu ei ole enää käynnissä: kerro säikeessä, että puhelu on päättynyt.

4. Anna agentin kysyä sinulta

Anna agentille työkalu, esimerkiksi ask_owner, jossa on yksi question- parametri ja joka kutsuu palvelintasi. Luo se API-yhteytenä ja liitä se agenttiin. Jokaisessa työkalupyynnössä puhelu välitetään X-ThunderPhone-Call-ID- otsakkeessa.

Vastauksen voi palauttaa kolmella tavalla.

Pidä puhelu odotustilassa (enintään 10 minuuttia). Aseta työkalu odotustilaan: spec.wait_mode "hold" ja spec.timeout enintään 600 sekuntiin (ilman aikakatkaisua odotus kestää 20 sekuntia) API:n kautta tai pyydä Zeusia asettamaan ne (sovelluksen muokkaimissa ei vielä ole kumpaakaan kenttää). Päätepisteesi lähettää kysymyksen puhelun ketjuun ja vastaa heti odottavalla tuloksella:

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

Toinen osapuoli kuulee agentilta yhden lauseen ja sen jälkeen pitomusiikkia. Puhelinvalikossa tai vastaajassa agentti käyttää sen sijaan puhuttuja tilannepäivityksiä, eikä täysdupleksiagentti pidä puhelua pidossa: se saa odottavan vastauksen tuloksena. Kun vastaus saapuu ketjuun, toimita se POST /v1/calls/{call_id}/tool-results -pyynnöllä:

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

Musiikki vaimenee ja agentti jatkaa vastauksellasi. Jos kukaan ei vastaa ennen timeout-ajan päättymistä, agentille kerrotaan, ettei vastausta saatu, ja se ehdottaa toiselle osapuolelle seuraavia toimia. Kun puhelulle on odottava kysymys, sen ketjuun tuleva seuraava vastaus vastaa siihen: toimita se työkalun tuloksena äläkä lähetä sitä myös kuiskauksena (kuiskaus tavoittaa agentin vasta työkalun palautettua tuloksen). Katso Pitkät odotusajat.

Odota pyynnössä (enintään 3 minuuttia). Päätepisteesi lähettää kysymyksen, odottaa vastausta ja palauttaa sen, esimerkiksi {"answer": "Yes, book Tuesday at 10."}. Aseta työkalun spec.timeout API:n kautta enintään 180 sekuntiin (oletusarvo on 20). Aseta päätepisteellesi oma määräaika muutamaa sekuntia lyhyemmäksi (esimerkiksi 170 sekuntiin), jotta se palauttaa myös silloin, kun kukaan ei vastaa, jotain mistä agentti voi jatkaa, esimerkiksi {"answer": null, "note": "No reply yet. Offer to take a message."}. Työkalu, joka saavuttaa timeout-ajan, saapuu agentille virheenä, ja palvelimesi on pidettävä pyyntö avoimena niin kauan. Odottaessaan agentti kertoo toiselle osapuolelle tarkistavansa asiaa, sanoo noin 12 sekunnin jälkeen työskentelevänsä edelleen ja antaa sitten lyhyen tilannepäivityksen noin 15 sekunnin välein. Pitotila toimii myös tässä: aseta spec.wait_mode arvoon "hold", jolloin toinen osapuoli kuulee tilannepäivitysten sijaan musiikkia.

Vastaa kuiskauksella. Päätepisteesi lähettää kysymyksen ja palauttaa heti vastauksen, esimerkiksi {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Kun vastaus saapuu, lähetä se kuiskauksena (vaihe 3), ja agentti reagoi siihen heti. Käytä tätä vastauksiin, joiden saaminen voi kestää yli 10 minuuttia. Puhelua ei pidetä pidossa: kehotteessasi tulee kertoa agentille, mitä sen pitää tehdä sillä välin, esimerkiksi pitää seuraa tai tarjota takaisinsoittoa.

Kerro jokaisessa tapauksessa agentin kehotteessa, milloin työkalua käytetään ja mitä toiselle osapuolelle kerrotaan odotuksen aikana:

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.

Huomioitavat rajoitukset

  • Päätepisteesi on vastattava työkalun timeout-ajan kuluessa, enintään 180 sekunnissa. Pitotilassa oleva työkalu voi pitää puhelun pidossa enintään 600 sekuntia odottavan tuloksen kanssa.
  • Kun työkalu odottaa, agentti ei vastaa toiselle henkilölle. Pitotilassa hän kuulee musiikkia; muussa tapauksessa lyhyitä puhuttuja tilannepäivityksiä.
  • Kuiskauksen enimmäispituus on 1000 merkkiä.
  • telephony.turn toimitetaan vähintään kerran, ja toimitukset voivat olla väärässä järjestyksessä.

Tietoturvan tarkistuslista

  • Säilytä API-avain palvelimellasi.
  • Varmista ThunderPhonen allekirjoitukset webhookeissa ja työkalupyynnöissä sekä Slackin allekirjoitussalaisuus Slackin pyynnöissä. ThunderPhonen kaksi allekirjoitusta käyttävät eri salaisuuksia: webhook-toimitukset käyttävät webhook- päätepisteen omaa salaisuutta, ja työkalupyynnöt käyttävät organisaatiosi webhook- salaisuutta, joka haetaan osoitteesta GET /v1/webhook.
  • Päätä, kuka saa aloittaa puheluita: tarkista Slack-käyttäjätunnus ennen puhelun soittamista.
  • Lähtevät puhelut noudattavat samoja sääntöjä kuin muutkin puhelut. Katso lähtevien puheluiden lait.

Rakenna se koodausagentilla

Ohjaa koodausagenttisi dokumentaation MCP-palvelimelle ja tälle sivulle ja pyydä sitä luomaan ”Slack-botti ThunderPhone-agentilleni, joka noudattaa tätä opasta”. ThunderPhone-sovelluksen avustaja Zeus voi määrittää agentin puolen (webhook-päätepisteen, työkalun ja kehotteen rivit) sekä kirjoittaa botille aloituskoodin chattiin.