Open in
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 chatissa | Bottisi kutsuu | Mitä tapahtuu |
|---|---|---|
| Lähetä "Soita Comcastille ja selvitä käyttökatkon arvioitu korjausaika" | POST /v1/call, jossa viesti on context | Agentti soittaa. Bottisi avaa puhelulle keskusteluketjun |
| Seuraa keskusteluketjua | Vastaanottaa telephony.turn-webhookeja | Jokainen agentin tai toisen henkilön sanoma rivi näkyy keskusteluketjussa |
| Vastaa keskusteluketjussa kesken puhelun | POST /v1/calls/{call_id}/whisper | Agentti saa viestisi yksityisesti ja toimii sen mukaan. Toinen henkilö ei koskaan kuule sitä |
| Vastaa agentin kysymykseen | Oma työkalupäätepisteesi palauttaa vastauksesi tai toimittaa sen myöhemmin komennolla POST /v1/calls/{call_id}/tool-results | Agentti jatkaa puhelua vastauksesi perusteella; pitotilassa toinen henkilö kuulee sillä välin odotusmusiikkia |
| Lue tulos | Vastaanottaa telephony.complete-webhookin | Bottisi 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- jatelephony.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 lopunsummaryedellyttää 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.turntoimitetaan 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.