telephony.incoming / web.incoming

Estävä webhook, joka määrittää saapuvan puhelun asetukset reaaliajassa.

Kun saapuva puhelu saapuu numeroon ilman määritettyä agenttia tai verkkowidgetin istunto käynnistyy julkisella avaimella tilassa mode="webhook", ThunderPhone lähettää estävän telephony.incoming / web.incoming -pyynnön vanhaan webhook-URL-osoitteeseesi ja odottaa määritysvastausta: puhelulle enintään 13 sekuntia, sisältäen yhden uudelleenyrityksen, ja widgetin istunnolle enintään 10 sekuntia (katso Aikakatkaisut ja uudelleenyritykset). Käytä tätä vaihtoa kehotteen, äänen ja työkalujen dynaamiseen valintaan puhelukohtaisesti — katso kokonaisvaltainen toimintamalli dynaamisen puhelumäärityksen oppaasta.

Aikakatkaisut ja uudelleenyritykset#

Vastaa nopeasti: soittaja odottaa linjalla, kun teet päätöstä.

Puhelussa (telephony.incoming):

• Ensimmäinen yritys voi kestää enintään 10 sekuntia.
• Jos se aikakatkaistaan, yhteyttä ei voida muodostaa tai se saa vastauksen 5xx, 408 tai 429, ThunderPhone yrittää vielä kerran. Uudelleenyritys saa käyttöönsä sen osuuden koko vaihdolle varatusta 13 sekunnin ajasta, joka on jäljellä: noin 3 sekuntia aikakatkaistun ensimmäisen yrityksen jälkeen ja lähes kaikki 13 sekuntia nopean epäonnistumisen jälkeen. Uudelleenyritystä ei tehdä, jos aikaa olisi jäljellä alle 2 sekuntia.
• Mikä tahansa muu 4xx-vastaus, kokorajan ylittävä vastaus tai 2xx-vastaus, jonka runko ei ole kelvollinen määritys, on lopullinen eikä sitä yritetä uudelleen.
• Molemmat yritykset lähettävät saman rungon, saman X-ThunderPhone-Signature-otsakkeen ja saman X-ThunderPhone-Idempotency-Key-otsakkeen (telephony-incoming-<call_id>), joten sivuvaikutuksia aiheuttava käsittelijä voi tunnistaa uudelleenyrityksen.

Varapuheagenttia ei ole. Jos käyttökelpoista määritystä ei saada, puhelu lopetetaan heti sen sijaan, että soittaja jätettäisiin hiljaiselle linjalle. Se näkyy puheluhistoriassa epäonnistuneena, laskuttamattomana puheluna, jonka end_reason on inbound_config_webhook_failed, ja tavallinen telephony.complete-tapahtuma lähetetään.

Widget-istunto (web.incoming) saa yhden, enintään 10 sekuntia kestävän yrityksen. Jos se epäonnistuu, istuntopyyntö epäonnistuu koodilla 502 tai 422.

Pyynnön sisältö#

Puheluille (telephony.incoming):

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

Web-widget-istunnoissa (web.incoming) data tunnistaa puhelinnumeroiden sijaan upottavan sivun:

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

Ohituskentät (language, voice, website_context ja mahdolliset selaimen variables) saapuvat vain, kun julkaistava avain sallii ne browser overrides -asetuksissaan. Istuntopyyntö, joka sisältää avaimen kieltämän ohituksen, hylätään ennen kuin tätä webhookia kutsutaan.

Vastausskeema#

Palauta JSON-objekti, joka kuvaa tämän puhelun agentin määrityksen. prompt ja voice ovat pakollisia; kaikki muu on valinnaista.

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

Koska prompt ja voice ovat pakollisia, arvon {} tai minkä tahansa validoinnissa epäonnistuvan vastauksen palauttaminen hylkää puhelun: puhelu päätetään kohdassa Aikakatkaisut ja uudelleenyritykset kuvatulla tavalla, ja pienoisohjelmaistunnon pyyntö epäonnistuu koodilla 422. Tällä polulla ei ole staattisen agentin varavaihtoehtoa (webhook-tilassa olevalla numerolla tai avaimella ei ole määritettyä agenttia).

Vastauksen kokorajoitus#

Esimerkkikäsittelijä#

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({});
  },
);

Vastaus toimintotyökaluilla#

Liitä työkaluja, jotta tekoäly voi kutsua rajapintojasi keskustelun aikana:

{
  "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"
        }
      }
    }
  ]
}

Tuotetason pikaopas#

Aiheeseen liittyvät#