telephony.incoming / web.incoming

Blokeeriv veebikonks, mis kujundab sissetuleva kõne konfiguratsiooni reaalajas.

Kui sissetulev telefonikõne jõuab numbrile ilma määratud häälagendita (sinu väljaminevatele kõnedele tagasi helistavate helistajate kohta vaata tagasihelistamisi) või veebividina seanss käivitub avaldatava võtmega režiimis mode="webhook", saadab ThunderPhone sinu vanale webhooki URL-ile blokeeriva päringu telephony.incoming / web.incoming ja ootab konfiguratsioonivastust: telefonikõne puhul kuni 13 sekundit, sealhulgas üks korduskatse, ja vidinaseansi puhul kuni 10 sekundit (vaata aegumisi ja korduskatseid). Kasuta seda vahetust, et valida iga kõne jaoks dünaamiliselt viip, hääl ja tööriistad — täielikku mustrit vaata dünaamilise kõnekonfiguratsiooni juhendist.

Määratud häälagendiga number vastab selle agendiga. Kui agendil on oma kõne seadistamise veebikonks, toimub sama blokeeriv suhtlus esmalt agendi URL-is, et täita agendi muutujad ja kõne kontekst.

Aegumised ja korduskatsed#

Vasta kiiresti: helistaja ootab liinil, kuni otsustad.

Telefonikõne (telephony.incoming) korral:

• Esimene katse võib kesta kuni 10 sekundit.
• Kui see aegub, ei saa ühendust või saab vastuse 5xx, 408 või 429, proovib ThunderPhone veel ühe korra. Korduskatse saab kogu vahetuse 13-sekundilisest ajapiirangust allesjäänud aja: umbes 3 sekundit pärast aegunud esimest katset ja kiire tõrke korral peaaegu kõik 13 sekundit. Korduskatset ei tehta, kui alles jääks vähem kui 2 sekundit.
• Mis tahes muu 4xx vastus, vastus, mis ületab suuruse piirangu, või 2xx, mille sisu ei ole kehtiv konfiguratsioon, on lõplik ja seda ei korrata.
• Mõlemad katsed saadavad sama sisu, sama X-ThunderPhone-Signaturei ja sama X-ThunderPhone-Idempotency-Key päise (telephony-incoming-<call_id>), nii et kõrvalmõjudega käitleja saab korduskatse ära tunda.

Kui kasutuskõlblikku konfiguratsiooni ei saabu, lõpetatakse kõne kohe, selle asemel et jätta helistaja vaiksele liinile. Kõne kuvatakse kõneajaloos ebaõnnestunud, arveldamata kõnena väärtusega end_reason inbound_config_webhook_failed ning saadetakse tavapärane telephony.complete sündmus. Kõne lehel juhtpaneelil ning config_webhook_failure-is GET /v1/calls/{call_id} on kirjas, mida sinu veebikonks tegi: {kind, attempts, http_status, host, source}, kus kind on http_error, timeout, connection, dns, tls, response_too_large, blocked_url, other, invalid_json, non_object_json või invalid_config, host on sinu veebikonksu hostinimi ja source on number (see veebikonks) või agent_setup (häälagendi kõne seadistamise veebikonks). Väärtuse invalid_config korral selgitab reason, miks vastust ei saanud kasutada, ning fields nimetab sellega seotud väljad: no_agent (puuduvad nii agent_id kui ka prompt; fields loetleb eiratud võtmed, näiteks valesti kirjutatud agentId), agent_not_found, agent_id_not_integer, unexpected_fields (võtmed peale variables, context, timezone ja language väärtuse agent_id kõrval), invalid_variables, invalid_context, invalid_language, unsupported_language, invalid_config_fields või agent_settings_invalid. Muudel juhtudel on reason väärtusega null ja fields on tühi. Ainus erand on helistaja, kes helistab tagasi ühele sinu väljaminevale kõnele, kui päring ise ebaõnnestus: vaata tagasikõnesid.

Vidina seansil (web.incoming) on üks katse, mis võib kesta kuni 10 sekundit. Kui see nurjub, nurjub seansitaotlus vastusega 502 või 422.

Päringu sisu#

Telefonikõnede jaoks (telephony.incoming):

{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567"
  }
}

Veebividina seansside puhul (web.incoming) tuvastab data telefoninumbrite asemel manustatud lehe:

{
  "type": "web.incoming",
  "data": {
    "call_id": 987654322,
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2"
  }
}

Alistusväljad (language, voice, website_context ja kõik brauseri variables) saabuvad ainult siis, kui avalik võti lubab neid oma brauseri alistustes. Seansitaotlus, mis sisaldab väärtust, mida võti ei luba, lükatakse tagasi enne selle webhooksi kutsumist.

Vastuse skeem#

Tagasta JSON-objekt, mis kirjeldab selle kõne häälagendi konfiguratsiooni. prompt ja voice on kohustuslikud; kõik muu on valikuline.

{
  "prompt":  "You are a helpful booking assistant for Acme Restaurant.",
  "voice":   "john",
  "product": "spark",
  "background_track": null,
  "tools":   []
}

Kuna prompt ja voice on kohustuslikud, lükkab {} või mis tahes valideerimise nurjav vastus kõne tagasi: telefonikõne lõpetatakse, nagu on kirjeldatud jaotises Ajalõpud ja korduskatsed, ning vidina seansitaotlus nurjub koodiga 422. See kehtib ka tagasihelistajate puhul: mis tahes JSON-objekt, mille sinu veebikonks tagastab, on selle vastus ning {} on viis kõnest keeldumiseks.

Häälagendi kõne seadistamise webhook#

Häälagendil võib olla oma kõne seadistamise webhook: tema seadete väli Kõne seadistamise webhook või API call_setup_webhook_url. Määra häälagent numbrile ning enne iga sellele numbrile saabuvat kõnet, millele häälagent vastab, küsib ThunderPhone webhookilt selle kõne muutujaid ja konteksti. Numbrile jääb määratud häälagent, seega näitavad telefoninumbrite leht ja häälagendi leht, milline häälagent sellele vastab.

See on seadistus nagu häälagendi teisedki: see on mustandina, avaldatakse juurutamisel ja säilitatakse versiooniajaloos. Number, mis on vanema versiooni külge kinnitatud, kasutab selle versiooni URL-i. Päringud allkirjastatakse häälagendi enda call_setup_webhook_signing_secret-iga (mitte organisatsiooni webhooki saladusega) ning neil on sama päis X-ThunderPhone-Signature, aegumistähtajad, korduskatsed ja idempotentsusvõti nagu eespool. Saladus on ainult kirjutatav: määra selline väärtus, mida sinu lõpp-punkt kontrollib (häälagendi seadetes või käsuga PATCH /v1/agents/{id}); ükski lugemispäring seda ei tagasta ning call_setup_webhook_signing_secret_set näitab, kas see on määratud.

Päring sisaldab ülaltoodud telephony.incoming-i kasulikku koormust koos täiendatava häälagendiga:

{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567",
    "variables":   null,
    "agent": {
      "id": 12,
      "name": "Front desk",
      "version": 7,
      "version_pinned": false
    }
  }
}

Vasta kõne jaoks vajalikuga. Kõik järgnevad täiendavad määratud häälagenti numbri versioonis:

• {"variables": {...}}, {"context": "..."} või mõlemad
• sama, kui "agent_id" väärtuseks on määratud häälagendi ID
• {}: häälagent vastab ilma midagi täitmata

Lubatud on ka timezone ja language, nagu agent_id kõrval. Muutujad täidavad häälagendi {{placeholders}}; kontekst lisatakse viiba järel.

Või määra kõne ise. Teise häälagendi agent_id või täielik konfiguratsioon koos prompt-iga vastab sellele üksikule kõnele määratud häälagendi (ja selle kinnitatud versiooni) asemel. Kõne üksikasjades tähistatakse iga juhtumit väljal call_setup_webhook: assigned_agent, other_agent või inline_config. Vastus, mida ei saa kasutada (tundmatu agent_id, muud võtmed koos variables-iga või konfiguratsioon, mis ei läbi valideerimist), lõpetab kõne samamoodi nagu numbri webhooki puhul.

Millal webhook peab vastama. Häälagent vajab oma webhooki, kui selle seadetes kasutatakse vaikimisi väärtuseta {{variable}}-it: viibas või taaskasutatavates juhistes, sammu juhistes või ridades, kinnituse viibas, kõnepostiteates, nõusolekuteates või {{variable}}-iga edastamisnumbris. Häälagendi call_setup_webhook_variables loetleb need.

• See vajab webhooki: kui webhook aegub, pole kättesaadav või vastab veaga või sisuga, mis pole JSON-objekt, siis kõne ei alga isegi juhul, kui kõnes on juba ühe sellise muutuja väärtus. Kõne lõpetatakse ja salvestatakse täpselt nii, nagu on kirjeldatud jaotises Aegumistähtajad ja korduskatsed (end_reason inbound_config_webhook_failed, arveldamata).
• See ei vaja midagi (muutujaid pole või igal neist on vaikeväärtus, näiteks {{first_name|there}}): webhook käivitub siiski, kuid selle ebaõnnestumisel vastab häälagent ilma selleta ning kõne üksikasjades kuvatakse webhook_failed koos ebaõnnestumise põhjusega.

Ainuüksi kõne kontekst ei muuda veebikonksu kunagi kohustuslikuks: agendi seadetes ei ole midagi, mis ütleks, et see vajab konteksti. Kasuta vaikeväärtuseta muutujat, kui kõne ei tohi alata ilma sinu veebikonksu vastuseta.

Määramine ja juurutamine. Agent, mis vajab oma veebikonksu, ei saa ilma selleta numbrile määratud olla: määramine lükatakse tagasi muutujate nimedega sõnumiga. Sama kontroll tehakse, kui numbri versioon muutub, sealhulgas kui kinnitatud number liigub tagasi väärtusele Latest. Kui agent vastab numbril oma avaldatud seadistustega, lükatakse samal viisil tagasi juurutamine, mis lisab sellise muutuja ilma veebikonksuta (või eemaldab veebikonksu). Mustandi salvestamine on alati lubatud ning agendi warnings sisaldab väärtust call_setup_webhook_needed, kuni probleem on lahendatud.

Agendi veebikonks käivitub ainult sissetulevate telefonikõnede puhul numbritel, millele see on määratud. Väljuvad kõned, veebividina seansid, SIP-aadressid, simulatsioonid ja juhtpaneeli testvestlused seda ei kutsu; need võtavad oma muutujad jätkuvalt päringust nagu varem.

Testimine salvestatud näidistega. Et testida, kuidas sinu agent toimib konkreetse vastusega (tagasi helistav helistaja, kirjet ei leitud, hispaania keelt kõnelev helistaja), salvesta see vastus agendi näidisena: selle variables, context ja soovi korral language, sisestades need käsitsi või kopeerides varasemast kõnest. Vali see, kui alustad juhtpaneelil testvestlust, testkõnet oma telefonile või simulatsiooni agendiga, ning kõne käivitub nii, nagu sinu webhook oleks sellele vastanud. Näidised on ühised agendi kõigi versioonide vahel. Ühe muutmine säilitab selle varasemad versioonid: kui agendi muudatus vajab muutujat, mida näidis ei määra, lisa see näidisele ning agendi vanemad versioonid jätkavad näidise kasutamist sellisena, nagu see oli. Telefoninumbrile helistavad simulatsioonid käivitavad selle asemel sinu tegeliku webhooki.

Ilma määratud agendita numbrid kasutavad jätkuvalt numbri või organisatsiooni veebikonksu täpselt nagu eespool.

Tagasihelistamised#

Inimesed helistavad sageli tagasi numbrile, mis neile helistas, näiteks pärast seda, kui sinu häälagent jättis kõneposti. Kui sissetulev kõne tuleb numbrilt, millele helistati viimase 30 päeva jooksul, leiab ThunderPhone kõige hiljutisema sellise väljamineva kõne (sellise, mis selle numbril helises) ja kasutab seda kolmel viisil:

1. returning_call päringus. Ülaltoodud blokeeriv päring ja lõpp-punkti teade sisaldavad seda, et sinu töötleja saaks helistaja suunata:

   {
     "type": "telephony.incoming",
     "data": {
       "call_id": 987654321,
       "from_number": "+14155550199",
       "to_number": "+15551234567",
       "returning_call": {
         "call_id": 987650001,
         "agent_id": 13,
         "started_at": "2026-10-21T19:05:12.402Z",
         "outcome": "voicemail"
       }
     }
   }

   Väli	Tüüp	Kirjeldus
   call_id	täisarv	Varasem väljaminev kõne
   agent_id	täisarv | null	Häälagent, kes kõne tegi; null kõne puhul, mis tehti tekstisisese konfiguratsiooniga või mille häälagent on kustutatud
   started_at	sõne	Millal see algas (ISO 8601, UTC)
   outcome	sõne	no_answer (kõne helises vastuseta, number oli hõivatud või kõne lükati tagasi), voicemail (kõnepost vastas või keegi ei rääkinud häälagendiga), conversation (keegi rääkis häälagendiga) või answered (kõnele vastati; veel ei ole teada, kes vastas)

2. Taustteave häälagendile. Kõnele vastav häälagent saab oma viiba lõppu lühikese märkuse: millal varasem kõne tehti, milline häälagent selle tegi ja milline oli tulemus. Häälagendile öeldakse, et ta ei loeks seda ette ning et ta ei jagaks helistaja ID võimaliku võltsimise tõttu selle kõne kohta midagi peale selle, et sellele numbrile helistati varem.

3. Varuagent. Kui numbril ei ole sissetulevate kõnede häälagenti ja konfiguratsiooni ei saabu, sest webhooki URL puudub või sinu webhook ei vastanud (aegus, sellele ei saanud ühendust või see vastas mõlemal katsel 5xx, 408 või 429), suunatakse kõne lõpetamise asemel varasema kõne teinud häälagendile, tingimusel et see häälagent on sinu organisatsioonis endiselt olemas. See töötab selle häälagendi juurutatud seadetega. Webhooki mis tahes vastus on siiski määrav: teine 4xx, sisu, mis ei ole JSON-objekt, {} või valideerimisel ebaõnnestuv konfiguratsioon lõpetab kõne nagu varem. Numbril olev sissetulevate kõnede häälagent vastab alati.

Varasema kõne üksikasjade jagamine. Helistaja ID-d saab võltsida, seega ei jõua vaikimisi varasema kõne sisust midagi uue kõneni. Organisatsiooni administraator saab sisse lülitada Varasema kõne üksikasjade jagamise jaotises Organisatsioon → Üldine → Tagasihelistamised (või määrata callback_context_details_enabled). Kui see on sisse lülitatud, tsiteerib häälagendi märkus ka varasema kõne kokkuvõtet ning varasema kõne teinud häälagendile suunatud kõne töötab selle kõne variables-ega (näiteks kontakti nimega). Lülita see sisse ainult siis, kui neid üksikasju on ohutu jagada igaühega, kes sellelt numbrilt helistab. Isegi siis ei edasta kõne, mis võib sisaldada kaitstud terviseteavet, kunagi oma kokkuvõtet ega muutujaid kõnele, mis ei ole määratud PHI-d töötlema.

Kõne üksikasjades. Varasema kõnega sobitunud sissetuleval kõnel on GET /v1/calls/{call_id} vastuses callback-objekt: ülaltoodud returning_call, routed_as_callback (kas varuagent sellele vastas) ja config_webhook_failure ({kind, attempts, http_status, host}, kui sinu veebikonks ei andnud vastust ja varuagent võttis kõne vastu, muul juhul null), mistõttu jääb veebikonksu katkestus nähtavaks ka siis, kui kõnele vastati.

Vastuse suuruse piirang#

Näidistöötleja#

import hashlib
import hmac
import json
import os
 
from fastapi import FastAPI, HTTPException, Request
 
app = FastAPI()
WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
 
def verify(body: bytes, signature: str) -> bool:
    expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")
 
@app.post("/thunderphone-webhook")
async def webhook(request: Request):
    body = await request.body()
    if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
        raise HTTPException(status_code=401)
 
    event = json.loads(body)
    if event["type"] == "telephony.incoming":
        caller = event["data"]["from_number"]
        prompt = (
            "Greet the caller as a San Francisco local…"
            if caller.startswith("+1415")
            else "You are a friendly customer support agent…"
        )
        return {
            "prompt": prompt,
            "voice": "john",
            "product": "spark",
        }
    if event["type"] == "web.incoming":
        return {
            "prompt": "You are the website's helpful voice assistant…",
            "voice": "john",
            "product": "spark",
        }
    return {}

import crypto from "node:crypto";
import express from "express";
 
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
 
function verify(body, signature) {
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(body)
    .digest("hex");
  return signature &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
 
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
 
    if (event.type === "telephony.incoming" || event.type === "web.incoming") {
      const caller = event.data.from_number || "web";
      const prompt = caller.startsWith("+1415")
        ? "Greet the caller as a San Francisco local…"
        : "You are a friendly customer support agent…";
      return res.json({
        prompt,
        voice: "john",
        product: "spark",
      });
    }
    res.json({});
  },
);

Vastus funktsioonitööriistadega#

Lisa tööriistad, et tehisintellekt saaks vestluse ajal sinu API-sid kasutada:

{
  "prompt":  "You are a booking assistant. Use the available tools to help customers schedule appointments.",
  "voice":   "john",
  "product": "spark",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_appointments",
        "description": "Find available appointment slots",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "service": { "type": "string" }
          },
          "required": ["date"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/search",
        "method": "POST",
        "headers": {
          "X-Api-Key": "your-key"
        }
      }
    }
  ]
}

Toote tasemete kiirülevaade#

Seotud#