Open in
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
- Unajisajili kwa tukio la
telephony.incoming(simu) auweb.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. - ThunderPhone hukutumia
{call_id, from_number, to_number}(vipindi vya widget hubeba sehemu mahususi za widget badala ya namba — tazama muundo wa ombi). - Seva yako hujibu kwa usanidi wa ejenti (prompt, sauti, bidhaa, zana, maneno). ThunderPhone hutumia usanidi huo kwa simu.
- Hakuna ejenti mbadala. Ukirejesha
{}au usanidi usio sahihi, au ombi bado linashindwa baada ya jaribio la kurudia, simu hukatishwa mara moja na kurekodiwa kwaend_reasoninbound_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
promptnavoicechaguo-msingi (auagent_idiliyohifadhiwa). Kurudisha{}au hali ya hitilafu hukatisha simu.
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 ...
passimport 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:
| Sehemu | Aina | Maelezo |
|---|---|---|
prompt | mfuatano wa herufi (inahitajika) | Prompt ya mfumo kwa ejenti |
voice | mfuatano wa herufi (inahitajika) | Kitambulisho cha sauti kutoka GET /v1/voices |
product | mfuatano wa herufi | Tuma bolt. Chaguo-msingi ni spark, thamani ya zamani ambayo bado inakubaliwa. |
background_track | mfuatano wa herufi | null | Kitambulisho cha sauti ya mandharinyuma |
acknowledgement_prompt_mode | mfuatano wa herufi | auto au manual (thamani za zamani za bidhaa za -with-ack pekee) |
acknowledgement_prompt | mfuatano wa herufi | Inahitajika wakati modi ni manual |
language_switching | mfuatano wa herufi | Kwa ejenti za lugha nyingi, ask_first au follow_caller |
tools | mpangilio | Skena 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
Schema sahihi za ombi + jibu, zikiwemo kila ufunguo wa usanidi.
Sanidi HMAC kwa usahihi mara moja; itumie tena kila mahali.
Unganisha uelekezaji unaobadilika na zana za kila ejenti.
Majaribio tena, mpangilio, muda wa kuisha.