ThunderPhone v3 sasa inapatikana.Anza mwenyewe, kuanzia 2¢/dakika.Soma tangazo

Developer cookbook

Usanidi unaobadilika kwa kila simu

Chagua ejenti anayejibu — au andika upya prompt na mipangilio yake — kivyake kwa kila simu inayoingia, kwa kuongozwa na mantiki maalum katika webhook unayoidhibiti.

Kwa chaguomsingi, kila nambari ya simu na ufunguo unaoweza kuchapishwa una ejenti tuli iliyowekwa. Unapohitaji ubinafsishaji wa kila mpigaji au kila mgeni — uelekezaji wa VIP, muktadha wa mtumiaji aliyeingia, majaribio ya prompt ya A/B — badilisha hadi hali ya webhook na uruhusu seva yako iamue.

Jinsi inavyofanya kazi

  1. Unajisajili kwa tukio la telephony.incoming (simu) au web.incoming (widget). Zote ni webhook zinazozuia: ThunderPhone husubiri jibu lako kabla ya kuendelea na simu, hadi sekunde 13 kwa simu ya kawaida (jaribio moja la kurudia likijumuishwa) na sekunde 10 kwa kipindi cha widget.
  2. ThunderPhone hukutumia {call_id, from_number, to_number} (vipindi vya widget hubeba sehemu mahususi za widget badala ya namba — tazama muundo wa ombi).
  3. Seva yako hujibu kwa usanidi wa ejenti (prompt, sauti, bidhaa, zana, maneno). ThunderPhone hutumia usanidi huo kwa simu.
  4. Hakuna ejenti mbadala. Ukirejesha {} au usanidi usio sahihi, au ombi bado linashindwa baada ya jaribio la kurudia, simu hukatishwa mara moja na kurekodiwa kwa end_reason inbound_config_webhook_failed; ombi la kipindi cha widget hushindwa.

1. Sanidi mahali webhook itakapotumwa

Kwa nambari za simu, jiandikishe endpoint yako kwa 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"]
  }'

Jibu linajumuisha secret ya matumizi ya mara moja — ihifadhi; utaitumia kwa uthibitishaji wa sahihi.

Kwa vipindi vya wijeti, unda ufunguo unaoweza kuchapishwa katika mode="webhook" ukiwa na URL ya endpoint yako tayari imejumuishwa:

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

Wijeti itatuma POST kwenye URL hii kila kipindi kinapoanza.

2. Tekeleza kishughulikiaji

Kanuni tatu za kuzingatia:

  • Thibitisha sahihi kwenye kila ombi (tazama Thibitisha sahihi za webhook). Usiruke hatua hii katika dev — ifanye kwa usahihi mara moja na uitumie tena.
  • Jibu haraka. Jaribio la kwanza la simu hukatishwa baada ya sekunde 10 na mawasiliano yote baada ya 13, na kila sekunde ni ukimya kwa mpigaji. Fanya utafutaji wa hifadhidata ikihitajika, lakini usiite LLM za hatua za chini kwa usawazishaji — ikiwa unataka uzalishaji wa prompt unaobadilika, hesabu mapema na uhifadhi kwenye kache.
  • Rudi kwenye chaguo-msingi kwa usafi. Kwa hali yoyote isiyotarajiwa, jibu kwa prompt na voice chaguo-msingi (au agent_id iliyohifadhiwa). Kurudisha {} au hali ya hitilafu hukatisha simu.
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. Schema ya jibu

Mwili wa jibu unalingana na schema ya jibu la simu inayoingia haswa. Sehemu zinazotumiwa mara nyingi:

SehemuAinaMaelezo
promptmfuatano wa herufi (inahitajika)Prompt ya mfumo kwa ejenti
voicemfuatano wa herufi (inahitajika)Kitambulisho cha sauti kutoka GET /v1/voices
productmfuatano wa herufiTuma bolt. Chaguo-msingi ni spark, thamani ya zamani ambayo bado inakubaliwa.
background_trackmfuatano wa herufi | nullKitambulisho cha sauti ya mandharinyuma
acknowledgement_prompt_modemfuatano wa herufiauto au manual (thamani za zamani za bidhaa za -with-ack pekee)
acknowledgement_promptmfuatano wa herufiInahitajika wakati modi ni manual
language_switchingmfuatano wa herufiKwa ejenti za lugha nyingi, ask_first au follow_caller
toolsmpangilioSkena za ndani za zana za utendakazi — tazama Zana za Utendakazi

Hifadhi ejenti iliyohifadhiwa na utoe vigeu au muktadha

Rudisha {"agent_id": 12, "variables": {"name": "Ada"}} ili kutumia ejenti iliyohifadhiwa ya shirika hilo pamoja na data ya kila simu. Prompt yake inaweza kuwa na {{name}} au {{name|Friend}}. Vigeu vya webhook huunganishwa juu ya vigeu vya kiwango cha ombi; null hutumia chaguo-msingi la kishikilia nafasi, au maandishi matupu ikiwa hakuna lililotolewa. Thamani za mwisho na majina ambayo hayajatatuliwa huonekana katika maelezo ya simu na webhook za kukamilika. Ongeza context, mfuatano wa maandishi huru wa hadi herufi 20,000, ili kuipa ejenti maelezo mafupi ya simu hii (dokezo kutoka CRM yako, sababu unayotarajia simu); huongezwa baada ya prompt katika kizuizi kilichotenganishwa. Majibu ya ejenti iliyohifadhiwa hukubali tu agent_id, variables, context, timezone na language. Ikiwa prompt ipo, jibu hutumia usanidi wa ndani na hupuuza agent_id; prompt ya ndani lazima bado iwe halali. Ikiwa webhook yako ni webhook ya usanidi wa simu ya ejenti iliyoteuliwa yenyewe, unaweza pia kuacha agent_id na kurudisha tu variables, context, timezone au language ili kumweka ejenti huyo aliyeteuliwa (ikijumuisha pini yoyote ya toleo) kwa simu. Majibu ya usanidi wa ndani yanaweza pia kujumuisha variables na context. Majibu ya ejenti iliyohifadhiwa hutumia mgawanyo wa A/B uliotumwa wa ejenti kwenye simu za simu na wijeti, kisha huunda vigeu. Tazama vigeu vya simu kwa vikomo na usaidizi wa API ya kipindi. Usanidi wa kuzuia hutoka kwenye URL ya zamani ya nambari ya simu/shirika au ufunguo wa wijeti wa hali ya webhook; matukio yanayoingia ya mfumo wa endpoint ni arifa pekee.

Weka eneo la saa kwa kila simu

Ejenti mmoja anaweza kujibu mawasiliano yaliyo katika maeneo tofauti ya saa. Ongeza timezone, jina la IANA, kwenye jibu la ejenti iliyohifadhiwa au la ndani, na ejenti itasema tarehe na saa na kutoa nyakati katika eneo hilo kwa simu hii, badala ya eneo la saa la ejenti mwenyewe:

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

Tuma eneo badala ya alama ya muda katika variables: saa ya ejenti huendelea kusonga wakati wa simu, na muda unaotuma hupitwa na wakati. Thamani ambayo si eneo la IANA hupuuzwa na simu huunganishwa katika eneo la ejenti.

Weka lugha kwa kila simu

Ejenti mmoja anaweza kujibu katika kila moja ya lugha zake. Ongeza language, msimbo wa lugha unaotumika kama es (es-MX husomwa kama es), karibu na agent_id na simu huanza katika lugha hiyo:

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

Ejenti huizungumza kwa sauti yake ya lugha hiyo: ingizo lake la language_voices; vinginevyo, ikiwa native_voice_switching imewashwa, sauti asilia ambayo ejenti ingebadilisha hadi kwa lugha hiyo; au vinginevyo sauti yake yenyewe, ikiwa sauti hiyo inaweza kuzungumza lugha hiyo. Katika simu zisizorekodiwa, ThunderPhone pia hucheza taarifa ya uchakataji wa moja kwa moja katika lugha ya simu. Kisha lugha nyingine za ejenti na lugha yake kuu hubaki zinapatikana kwa kubadilisha. Ikiwa hakuna kati ya hizi inayoweza kuzungumza lugha hiyo, simu bado huanza katika lugha hiyo, kwa sauti chaguomsingi ya lugha hiyo (ejenti yenye sauti maalum huihifadhi) na bila lugha nyingine. Ikiwa simu baadaye itabadilika katikati ya simu hadi lugha nyingine ya ejenti, pia hutumia ingizo la language_voices la lugha hiyo wakati sauti zote mbili ni sauti za katalogi; vinginevyo kanuni za kawaida za kubadilisha hutumika. Ejenti za duplex kamili ni tofauti: katika lugha yoyote inayotumika, simu huhifadhi sauti ya ejenti yenyewe, na language_voices pamoja na kubadilisha sauti asilia havitumiki. Ni msimbo ambao si lugha inayotumika pekee unaokataliwa. Vipindi vya wijeti na vya wakati halisi hutumia sehemu ileile ya language.

Mifumo

Muktadha wa mtumiaji aliyeingia

Katika wijeti za hali ya webhook, ukurasa wa mgeni tayari unajua yeye ni nani. Piga webhook yako kwa kigezo cha mfuatano wa hoja ambacho SDK ya wijeti hupitisha (?customer_id=123) na umtafute mteja upande wa seva.

Utoaji wa prompt wa A/B

Kabla ya kutekeleza hili mwenyewe, fahamu kwamba ThunderPhone ina kipengele cha ndani cha Majaribio (/dashboard/experiments na kichupo cha A/B cha kiunda ejenti) kinachofafanua vibadala, kugawanya trafiki, na kulinganisha matokeo kwa kila kibadala — hakuna webhook inayohitajika.

Ikiwa bado unahitaji udhibiti upande wa webhook: fanya hesabu ya mseto wa call_id → kikundi; toa prompt A kwa 0..49 na prompt B kwa 50..99. Rekodi kikundi ulichochagua katika DB yako mwenyewe na baadaye ukihusianishe na alama ya simu iliyokamilika.

Uelekezaji kulingana na muda

Saa za kazi → ejenti wa "usaidizi wa moja kwa moja"; baada ya saa za kazi → ejenti wa "chukua ujumbe". Badilisha moja kwa moja kwa kutumia new Date().getUTCHours() katika kishughulikiaji chako.


Hatua zinazofuata