Skip to main content
Oletusarvoisesti jokaiselle puhelinnumerolle ja julkaistavalle avaimelle on määritetty staattinen agentti. Kun tarvitset soittajakohtaista tai kävijäkohtaista mukautusta — VIP-reititystä, kirjautuneen käyttäjän kontekstia tai A/B-kehotetestejä — vaihda webhook-tilaan ja anna palvelimesi päättää.

Näin se toimii

  1. Tilaa telephony.incoming (puhelin)- tai web.incoming (widget) -tapahtuma. Molemmat ovat estäviä webhookeja: ThunderPhone odottaa vastaustasi enintään 10 sekuntia ennen puhelun jatkamista.
  2. ThunderPhone lähettää sinulle {call_id, from_number, to_number} (widget- istunnot sisältävät numeroiden sijaan widget-kohtaisia kenttiä — katso pyyntöskeema).
  3. Palvelimesi vastaa agentin määrityksellä (kehote, ääni, tuote, työkalut). ThunderPhone käyttää tätä määritystä puhelussa.
  4. 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

Tilaa puhelinnumeroita varten päätepisteellesi telephony.incoming:
Vastaus sisältää kertaluonteisen 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äen new 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.