Näin se toimii
- Tilaa
telephony.incoming(puhelin)- taiweb.incoming(widget) -tapahtuma. Molemmat ovat estäviä webhookeja: ThunderPhone odottaa vastaustasi enintään 10 sekuntia ennen puhelun jatkamista. - ThunderPhone lähettää sinulle
{call_id, from_number, to_number}(widget- istunnot sisältävät numeroiden sijaan widget-kohtaisia kenttiä — katso pyyntöskeema). - Palvelimesi vastaa agentin määrityksellä (kehote, ääni, tuote, työkalut). ThunderPhone käyttää tätä määritystä puhelussa.
- Jos palautat
{}, vastaus aikakatkaistaan tai tapahtuu virhe, staattisesti määritettyä agenttia käytetään varavaihtoehtona. Turvallinen oletus.
Toimii samalla tavalla puheluissa (
telephony.incoming) ja widget-
istunnoissa (web.incoming), toimitetaanko ne webhook-päätepisteeseen
vai vanhaan yhden URL-osoitteen webhookiin.1. Määritä webhook-kohde
- Puhelut
- Web-widget
Tilaa puhelinnumeroita varten päätepisteellesi Vastaus sisältää kertaluonteisen
telephony.incoming:secret-arvon — tallenna se; käytät sitä
allekirjoituksen varmennukseen.2. Toteuta käsittelijä
Kolme nyrkkisääntöä:- Vahvista allekirjoitus jokaisessa pyynnössä (katso Vahvista webhook-allekirjoitukset). Älä ohita tätä kehityksessä — tee se oikein kerran ja käytä uudelleen.
- Vastaa nopeasti. Kymmenen sekuntia on ehdoton enimmäisaika, ja jokainen sekunti on soittajalle hiljaisuutta. Tee tarvittaessa tietokantahakuja, mutta älä kutsu jatkoketjun LLM:iä synkronisesti — jos haluat dynaamisen promptin luomisen, esilaske ja tallenna välimuistiin.
- Käytä selkeää varavaihtoehtoa. Kaikissa odottamattomissa tiloissa tulee palauttaa
{}, jotta staattisesti määritetty agentti käsittelee puhelun.
3. Vastausskeema
Vastauksen runko vastaa täsmälleen saapuvan puhelun vastausskeemaa. Yleisesti käytetyt kentät:Puhelukohtainen puhejärjestys ja
max_hold_seconds eivät ole käytettävissä
webhook-vastauksessa. Määritä ne siinä
agentissa, johon viittaat.Käyttömallit
Sisäänkirjautuneen käyttäjän konteksti
Webhook-tilan widgeteissä vierailijan sivu tietää jo, kuka hän on. Kutsu webhookiasi kyselymerkkijonoparametrilla, jonka widgetin SDK välittää (?customer_id=123), ja hae asiakas palvelinpuolella.
A/B-kehotteiden käyttöönotto
Ennen kuin toteutat tämän itse, huomaa, että ThunderPhonessa on sisäänrakennettu Kokeilut -ominaisuus (/dashboard/experiments ja agentin rakennustyökalun A/B-välilehti), joka
määrittää variantit, jakaa liikenteen ja vertaa tuloksia varianttikohtaisesti —
webhookia ei tarvita.
Jos tarvitset silti hallintaa webhook-puolella: hajauta call_id → ryhmä;
tarjoa kehote A arvoille 0..49 ja kehote B arvoille 50..99. Tallenna
valitsemasi ryhmä omaan tietokantaasi ja yhdistä se myöhemmin valmistuneen
puhelun arvioon.
Aikaperusteinen reititys
Aukioloaika → “live-tuki”-agentti; aukioloaikojen ulkopuolella → “jätä viesti” -agentti. Toteuta tämä käsittelijässäsi pelkkänä ehtovalintana käyttäennew Date().getUTCHours().
Seuraavat vaiheet
Saapuvan puhelun webhook-viite
Täsmälliset pyyntö- ja vastausskeemat, mukaan lukien kaikki määritysavaimet.
Vahvista webhook-allekirjoitukset
Tee HMAC oikein kerran; käytä sitä uudelleen kaikkialla.
Rakenna työkalintegraatio
Yhdistä dynaaminen reititys agenttikohtaisiin työkaluihin.
Toimitussemantiikka
Uudelleenyritykset, järjestys, aikakatkaisut.