ThunderPhone v3 jau veikia.Viską atlikite savarankiškai – nuo 2 ct/min.Skaityti pranešimą

Developer cookbook

Dinaminė konfigūracija kiekvienam skambučiui

Kiekvienam įeinančiam skambučiui atskirai pasirinkite atsiliepiantį agentą arba pakeiskite jo raginimą ir nustatymus, remdamiesi pasirinkta logika jūsų valdomame webhook.

Pagal numatytuosius nustatymus kiekvienam telefono numeriui ir viešajam raktui priskiriamas statinis agentas. Kai reikia tinkinti kiekvienam skambintojui arba kiekvienam lankytojui — nukreipti VIP klientus, įtraukti prisijungusio naudotojo kontekstą, atlikti A/B raginimų bandymus — perjunkite į žiniatinklio kabliuko režimą ir leiskite spręsti savo serveriui.

Kaip tai veikia

  1. Užsiprenumeruokite telephony.incoming (telefono) arba web.incoming (valdiklio) įvykį. Abu yra blokuojamieji žiniatinklio kabliai: ThunderPhone laukia jūsų atsakymo prieš tęsdamas skambutį — iki 13 sekundžių telefono skambučiui (įskaičiuotas vienas pakartotinis bandymas) ir 10 sekundžių valdiklio seansui.
  2. ThunderPhone siunčia jums {call_id, from_number, to_number} (valdiklio seansuose vietoj numerių pateikiami valdikliui būdingi laukai — žr. užklausos schemą).
  3. Jūsų serveris atsako agento konfigūracija (nurodymai, balsas, produktas, įrankiai, žodžiai). ThunderPhone naudoja šią konfigūraciją skambučiui.
  4. Atsarginio agento nėra. Jei grąžinate {} arba netinkamą konfigūraciją arba užklausa vis tiek nepavyksta po pakartotinio bandymo, telefono skambutis nedelsiant nutraukiamas ir užregistruojamas su end_reason inbound_config_webhook_failed; valdiklio seanso užklausa nepavyksta.

1. Sukonfigūruokite žiniatinklio kabliuko paskirties vietą

Telefono numeriams užsiprenumeruokite savo galinį tašką įvykiui telephony.incoming:

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod call-incoming",
    "url":    "https://example.com/thunderphone/incoming",
    "events": ["telephony.incoming"]
  }'

Atsakyme pateikiamas vienkartinis secret — išsaugokite jį; naudosite jį parašo tikrinimui.

Valdiklio sesijoms sukurkite viešąjį raktą su mode="webhook", kuriame įtraukta jūsų galinio taško URL:

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Dynamic widget",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-incoming",
    "allowed_domains": ["example.com"]
  }'

Valdiklis siųs POST užklausą į šį URL kiekvienos sesijos pradžioje.

2. Įdiekite tvarkytuvę

Trys pagrindinės taisyklės:

  • Patikrinkite parašą kiekvienoje užklausoje (žr. Tikrinkite žiniatinklio kablio parašus). Nepraleiskite šio veiksmo kūrimo aplinkoje — tinkamai įgyvendinkite vieną kartą ir naudokite pakartotinai.
  • Atsakykite greitai. Pirmasis telefono skambučio bandymas nutraukiamas po 10 sekundžių, o visas apsikeitimas — po 13, todėl kiekviena sekundė skambinančiajam yra tyla. Jei reikia, atlikite duomenų bazės užklausas, tačiau nekvieskite paskesnių LLM sinchroniškai — jei norite dinamiškai generuoti raginimus, iš anksto juos apskaičiuokite ir išsaugokite talpykloje.
  • Tvarkingai naudokite atsarginį variantą. Esant bet kokiai netikėtai būsenai, atsakykite numatytaisiais prompt ir voice (arba išsaugotu agent_id). Grąžinus {} arba klaidos būseną, skambutis nutraukiamas.
FastAPI
import hashlib
import hmac
import json
import os
 
from fastapi import FastAPI, HTTPException, Request
 
app = FastAPI()
SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
 
def verify(body: bytes, sig: str) -> bool:
    expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig or "")
 
@app.post("/thunderphone/incoming")
async def incoming(request: Request):
    body = await request.body()
    if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
        raise HTTPException(401)
 
    event = json.loads(body)
    if event["type"] not in ("telephony.incoming", "web.incoming"):
        return {}  # fall back to default
 
    caller = event["data"]["from_number"]
    # Cheap DB lookup: is this a known VIP?
    customer = lookup_customer(caller)
    if customer and customer.tier == "vip":
        return {
            "prompt":  f"You are a VIP concierge for {customer.name}. Be proactive…",
            "voice":   "john",
            "product": "storm-base",
        }
    return {}  # default agent handles non-VIPs
 
def lookup_customer(phone: str):
    # ... your CRM integration ...
    pass
Express
import crypto from "node:crypto";
import express from "express";
 
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
 
function verify(body, sig) {
  const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex");
  return sig &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}
 
app.post(
  "/thunderphone/incoming",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
 
    const IMPORTANT_TYPES = new Set([
      "telephony.incoming",
      "web.incoming",
    ]);
    if (!IMPORTANT_TYPES.has(event.type)) return res.json({});
 
    const customer = await lookupCustomer(event.data.from_number);
    if (customer?.tier === "vip") {
      return res.json({
        prompt:  `You are a VIP concierge for ${customer.name}. Be proactive…`,
        voice:   "john",
        product: "storm-base",
      });
    }
    res.json({}); // fall back to default agent
  },
);

3. Atsakymo schema

Atsakymo turinys tiksliai atitinka įeinančio skambučio atsakymo schemą. Dažniausiai naudojami laukai:

LaukasTipasAprašymas
prompteilutė (privaloma)Sisteminė agento instrukcija
voiceeilutė (privaloma)Balso identifikatorius iš GET /v1/voices
producteilutėSiųskite bolt. Numatytoji reikšmė yra spark – senesnė reikšmė, kuri vis dar priimama.
background_trackeilutė | nullAplinkos garso identifikatorius
acknowledgement_prompt_modeeilutėauto arba manual (tik senesnėms -with-ack produkto reikšmėms)
acknowledgement_prompteilutėPrivaloma, kai režimas yra manual
language_switchingeilutėDaugiakalbiams agentams: ask_first arba follow_caller
toolsmasyvasĮterptinės funkcijų įrankių schemos – žr. Funkcijų įrankiai

Išsaugokite agentą ir pateikite kintamuosius arba kontekstą

Grąžinkite {"agent_id": 12, "variables": {"name": "Ada"}}, kad naudotumėte tos organizacijos išsaugotą agentą su kiekvieno skambučio duomenimis. Jo raginime gali būti {{name}} arba {{name|Friend}}. Žiniatinklio kablio kintamieji sujungiami su užklausos lygio kintamaisiais; reikšmė null naudoja vietaženklio numatytąją reikšmę arba tuščią tekstą, jei ji nepateikta. Galutinės reikšmės ir neišspręsti pavadinimai rodomi skambučio išsamioje informacijoje ir užbaigimo žiniatinklio kabliuose. Pridėkite context – laisvos formos eilutę, sudarytą ne daugiau kaip iš 20 000 simbolių, kad suteiktumėte agentui informaciją apie šį skambutį (pastabas iš jūsų CRM, priežastį, dėl kurios tikitės skambučio); ji pridedama po raginimo atskirtame bloke. Išsaugoto agento atsakymai priima tik agent_id, variables, context, timezone ir language. Jei yra prompt, atsakyme naudojama įterptinė konfigūracija ir nepaisoma agent_id; įterptinis raginimas vis tiek turi būti galiojantis. Jei jūsų žiniatinklio kablys yra priskirto agento skambučio nustatymo žiniatinklio kablys, taip pat galite nenurodyti agent_id ir grąžinti tik variables, context, timezone arba language, kad skambučiui išlaikytumėte tą priskirtą agentą (įskaitant bet kokį versijos fiksavimą). Įterptinės konfigūracijos atsakymai taip pat gali apimti variables ir context. Išsaugoto agento atsakymuose naudojamas diegto agento A/B paskirstymas tiek telefono, tiek valdiklio skambučiams, tada atvaizduojami kintamieji. Žr. skambučio kintamieji apribojimams ir sesijos API palaikymui. Blokuojanti konfigūracija gaunama iš senstelėjusio telefono numerio / organizacijos URL arba valdiklio režimo valdiklio rakto; galinių taškų sistemos gaunami įvykiai yra tik pranešimai.

Nustatykite laiko juostą kiekvienam skambučiui

Vienas agentas gali atsiliepti kontaktams skirtingose laiko juostose. Pridėkite timezone – IANA pavadinimą – prie išsaugoto agento arba įterptinio atsakymo, ir šio skambučio metu agentas nurodys datą bei laiką ir pasiūlys laikus toje juostoje, o ne savo laiko juostoje:

{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}

Siųskite juostą, o ne laiko žymą per variables: skambučio metu agento laikrodis veikia toliau, todėl jūsų perduotas laikas pasensta. Reikšmė, kuri nėra IANA laiko juosta, ignoruojama, o skambutis sujungiamas naudojant agento laiko juostą.

Nustatykite kalbą kiekvienam skambučiui

Vienas agentas gali atsakyti kiekviena savo kalba. Pridėkite language – palaikomos kalbos kodą, pvz., es (es-MX skaitomas kaip es) – šalia agent_id, ir skambutis pradedamas ta kalba:

{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}

Agentas kalba šia kalba naudodamas tai kalbai skirtą balsą: savo language_voices įrašą; kitu atveju, jei įjungtas native_voice_switching, gimtąjį balsą, į kurį agentas persijungtų tai kalbai; kitu atveju savo balsą, jei tas balsas kalba šia kalba. Neįrašomuose skambučiuose ThunderPhone taip pat paleidžia tiesioginio apdorojimo pranešimą skambučio kalba. Tada kitos agento kalbos ir jo pagrindinė kalba lieka prieinamos perjungti. Jei nė viena iš jų negali kalbėti šia kalba, skambutis vis tiek pradedamas šia kalba, naudojant numatytąjį tos kalbos balsą (agentas su tinkintu balsu jį išlaiko) ir be kitų kalbų. Jei vėliau skambučio metu persijungiama į kitą agento kalbą, taip pat naudojamas tos kalbos language_voices įrašas, kai abu balsai yra katalogo balsai; kitu atveju taikomos įprastos perjungimo taisyklės. Viso duplekso agentams taikoma kita tvarka: bet kuria palaikoma kalba skambutis išlaiko paties agento balsą, o language_voices ir gimtojo balso perjungimas netaikomi. Atmetamas tik kodas, kuris nėra palaikomos kalbos kodas. Valdiklio ir realiojo laiko seansuose naudojamas tas pats language laukas.

Modeliai

Prisijungusio naudotojo kontekstas

Žiniatinklio kablio režimo valdikliuose lankytojo puslapis jau žino, kas jis yra. Iškvieskite savo žiniatinklio kablį su užklausos eilutės parametru, kurį valdiklio SDK persiunčia (?customer_id=123), ir suraskite klientą serverio pusėje.

A/B raginimų diegimas

Prieš kurdami tai patys, atkreipkite dėmesį, kad ThunderPhone turi vietinę eksperimentų funkciją (/dashboard/experiments ir agento kūrimo priemonės A/B skirtuką), kuri apibrėžia variantus, paskirsto srautą ir palygina kiekvieno varianto rezultatus — žiniatinklio kablio nereikia.

Jei vis tiek reikia valdymo žiniatinklio kablio pusėje: maišykite call_id → segmentas; pateikite raginimą A reikšmėms 0..49 ir raginimą B reikšmėms 50..99. Įrašykite pasirinktą segmentą savo DB ir vėliau susiekite jį su užbaigto skambučio įvertinimu.

Maršrutizavimas pagal laiką

Darbo valandos → „tiesioginio palaikymo“ agentas; ne darbo valandomis → „priimti žinutę“ agentas. Tvarkyklėje tiesiog perjunkite pagal new Date().getUTCHours().


Tolesni veiksmai