Open in
telephony.incoming / web.incoming
Webhook inayozuia inayounda usanidi wa simu inayoingia kwa wakati halisi.
Wakati simu inayoingia inapofikia nambari isiyo na ejenti
aliyekabidhiwa (tazama Simu za kurudia kwa wapigaji wanaorudisha
simu zako zinazotoka), au kipindi cha wijeti ya wavuti kinapoanza kwenye ufunguo unaoweza kuchapishwa katika
mode="webhook", ThunderPhone hutuma ombi linalozuia
la telephony.incoming / web.incoming kwenye
URL yako ya urithi ya webhook
na kusubiri jibu la usanidi: hadi sekunde 13 kwa
simu, ikijumuisha jaribio moja la kurudia, na hadi sekunde 10 kwa kipindi cha
wijeti (tazama Muda wa kuisha na majaribio ya kurudia). Tumia
mabadilishano haya kuchagua prompt, sauti na zana kwa njia inayobadilika kwa kila simu —
tazama mwongozo wa usanidi badilifu wa simu
kwa mtindo wa kuanzia mwanzo hadi mwisho.
Nambari iliyo na ejenti iliyowekwa hujibiwa na ejenti huyo. Ejenti anapokuwa na webhook yake mwenyewe ya usanidi wa simu, ubadilishanaji huohuo wa kuzuia hufanyika kwanza, kwenye URL ya ejenti, ili kujaza vigeu vya ejenti na muktadha wa simu.
Muda wa kuisha na majaribio upya
Jibu haraka: mpigaji anasubiri kwenye laini huku ukiamua.
Kwa simu (telephony.incoming):
- Jaribio la kwanza linaweza kuchukua hadi sekunde 10.
- Ikiwa muda wake unaisha, haliwezi kuunganishwa, au linapata jibu la
5xx,408au429, ThunderPhone hujaribu tena mara moja. Jaribio upya hupata muda unaosalia wa bajeti ya sekunde 13 kwa mabadilishano yote: takriban sekunde 3 baada ya jaribio la kwanza lililoishiwa na muda, na karibu sekunde 13 zote baada ya hitilafu ya haraka. Hakuna jaribio upya ikiwa zimesalia chini ya sekunde 2. - Jibu lingine lolote la
4xx, jibu linalozidi kikomo cha ukubwa, au2xxambayo mwili wake si usanidi halali ni la mwisho na halijaribiwi tena. - Majaribio yote mawili hutuma mwili uleule,
X-ThunderPhone-Signatureileile, na kichwa kilekile chaX-ThunderPhone-Idempotency-Key(telephony-incoming-<call_id>), ili kidhibiti chenye athari za kando kiweze kutambua jaribio upya.
Iwapo hakuna usanidi unaoweza kutumika unaowasili, simu hukatishwa mara moja
badala ya kumwacha mpigaji kwenye laini kimya. Huonekana katika historia ya simu
kama simu iliyoshindwa isiyotozwa bili yenye end_reason
inbound_config_webhook_failed, na tukio la kawaida la
telephony.complete hutumwa. Ukurasa wa simu
katika dashibodi, na config_webhook_failure katika
GET /v1/calls/{call_id}, huonyesha webhook yako
ilichofanya: {kind, attempts, http_status, host, source}, ambapo kind ni http_error,
timeout, connection, dns, tls, response_too_large,
blocked_url, other, invalid_json, non_object_json au
invalid_config, host ni jina la host ya webhook yako, na source ni
number (webhook hii) au agent_setup (webhook ya usanidi wa simu wa ejenti).
Kwa invalid_config, reason hueleza kwa nini jibu halikuweza kutumika na
fields hutaja nyuga zinazohusika: no_agent (si agent_id wala
prompt; fields huorodhesha funguo zilizopuuzwa, kama agentId yenye
tahajia isiyo sahihi), agent_not_found, agent_id_not_integer, unexpected_fields
(funguo tofauti na variables, context, timezone na language zilizo
kando ya agent_id), invalid_variables, invalid_context, invalid_language,
unsupported_language, invalid_config_fields au agent_settings_invalid.
Vinginevyo reason ni null na fields haina kitu. Isipokuwa pekee ni
mpigaji anayerejesha mojawapo ya simu zako za kutoka wakati ubadilishanaji
wenyewe ulishindwa: tazama Simu za kurejesha.
Kipindi cha wijeti (web.incoming) hupata jaribio moja la hadi sekunde 10.
Kikishindwa, ombi la kipindi hushindwa kwa 502 au 422.
Payload ya ombi
Kwa simu za simu (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| Sehemu | Aina | Maelezo |
|---|---|---|
call_id | integer | Kitambulisho cha simu — thabiti katika matukio yote ya simu hii |
from_number | string | Namba ya mpigaji katika E.164 |
to_number | string | Lengwa la E.164 (moja ya namba zako za ThunderPhone) |
returning_call | object | Hupo tu wakati namba hii ilimpigia mpigaji ndani ya siku 30 zilizopita. Tazama Simu za kurudia |
sip_headers | object | Hupo tu simu ilipowasili kupitia muunganisho wa SIP wa mwongozo wenye vichwa vya SIP vya X-* au User-to-User: jina la kichwa kwa herufi ndogo → thamani. Tazama Vichwa vya SIP |
Kwa vipindi vya wijeti ya wavuti (web.incoming), data hutambulisha
ukurasa unaopachika wijeti badala ya nambari za simu:
{
"type": "web.incoming",
"data": {
"call_id": 987654322,
"origin_domain": "https://example.com",
"publishable_key_prefix": "pk_live_a1b2"
}
}| Sehemu | Aina | Maelezo |
|---|---|---|
call_id | integer | Kitambulisho cha simu |
origin_domain | string | Asili ya ukurasa unaopangisha wijeti, kama ilivyotumwa na kivinjari. Mteja asiye wa kivinjari anaweza kutuma thamani yoyote, kwa hivyo usiichukulie kama uthibitisho wa mahali ombi lilipotoka |
publishable_key_prefix | string | Herufi za kwanza za ufunguo unaoweza kuchapishwa uliofungua kipindi |
language, primary_language | string | Hupo wakati kipindi cha wijeti kilipoomba ubatilishaji wa lugha |
voice | string | Hupo wakati kipindi cha wijeti kilipoomba ubatilishaji wa sauti |
website_context | string | Hupo wakati wijeti ilipopitisha muktadha wa ukurasa kwa kila kipindi |
Sehemu za ubatilishaji (language, voice, website_context, na
variables zozote za kivinjari) huwasili tu wakati ufunguo unaoweza kuchapishwa unaziruhusu katika
ubatilishaji wa kivinjari. Ombi la
kipindi lenye ubatilishaji ambao ufunguo haurusu hukataliwa kabla ya
webhook hii kuitwa.
Skima ya majibu
Rudisha kitu cha JSON kinachoeleza usanidi wa ejenti kwa simu hii.
prompt na voice zinahitajika; kila kitu kingine ni hiari.
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| Sehemu | Aina | Inahitajika | Maelezo |
|---|---|---|---|
prompt | string | ndiyo | Prompt ya mfumo inayoongoza ejenti |
voice | string | ndiyo | Kitambulisho cha sauti kutoka GET /v1/voices, kwa mfano john. voice_name inakubaliwa kama jina mbadala. Sauti zisizojulikana hushindwa uthibitishaji na kukataa simu |
product | string | hapana | Tuma bolt. Chaguo-msingi ni spark, thamani ya zamani ambayo bado inakubaliwa pamoja na storm-base, storm-base-with-ack, storm-extra na storm-extra-with-ack |
thinking_level | string | hapana | minimal, base (chaguo-msingi), au extra. Kwenye thamani za bidhaa za zamani za storm-*, storm-extra* hulazimisha extra na storm-* nyingine hulazimisha base |
audio_context_mode | string | hapana | full (chaguo-msingi) au reduced |
watchdog_enabled | boolean | hapana | Washa usimamizi kwa simu hii. Chaguo-msingi ni false |
additional_audio_context | boolean | null | hapana | Jumuisha zamu chache za mwisho za sauti ya mpigaji simu badala ya zamu ya hivi karibuni pekee, ili kuboresha masahihisho na ukusanyaji wa data wenye tahajia/namba nyingi kwa ongezeko dogo la muda wa kusubiri/gharama. Huwashwa kwa chaguo-msingi kwa vipindi vinavyoingia na huzimwa kwa simu zinazotoka; null huhifadhi chaguo-msingi |
storm_feedback_mode | string | hapana | none, acknowledgement (chaguo-msingi), au tick: kile mpigaji simu husikia wakati jibu la polepole zaidi linatayarishwa ikiwa audio_tier ni plus au max |
language | string | hapana | Ufupisho wa primary_language. Pia inaruhusiwa kando ya agent_id, ambapo ni lugha ambayo simu hii huanza nayo, ikisemwa kwa sauti ya ejenti kwa lugha hiyo; tazama Weka lugha kwa kila simu |
primary_language | string | hapana | Msimbo wa lugha, uliosanifishwa (chaguo-msingi en). Misimbo isiyoweza kutatuliwa hukataa simu |
has_additional_languages | boolean | hapana | Chaguo-msingi ni false |
additional_languages | array of string | hapana | Lugha za ziada ambazo ejenti inaweza kubadilisha kwenda |
native_voice_switching | boolean | hapana | Chaguo-msingi ni false. Simu inapobadilisha hadi lugha nyingine, badilisha hadi sauti asilia ya lugha hiyo (inayolingana kwa jinsia) badala ya kuhifadhi sauti iliyosanidiwa |
language_switching | string | null | hapana | ask_first (chaguo-msingi) au follow_caller; null ni sawa na ask_first. Jinsi ejenti ya lugha nyingi inavyoshughulikia mtu mwingine anapozungumza lugha nyingine miongoni mwa lugha zake. ask_first hubadilisha mara moja anapoomba lugha hiyo au kusema sentensi kamili kwa lugha hiyo, na huuliza kama waendelee nayo baada ya kitu kifupi, kama "ndiyo". follow_caller hubadilisha hadi lugha yoyote iliyosanidiwa wanayozungumza, hata neno moja. Hutumika tu wakati additional_languages imewekwa |
audio_tier | string | null | hapana | Kwa product: "bolt" pekee. Usikivu: jinsi ejenti inavyomsikia mpigaji simu kwa umakini. standard (chaguo-msingi; "" na null zina maana sawa) inafaa kwa simu nyingi (simu zinazoshughulikia PHI hutumia watoa huduma waliofunikwa na BAA pekee). lite ndiyo ya bei nafuu zaidi na husikia vibaya mara nyingi zaidi. plus husikiliza kwa umakini zaidi kwenye zamu ngumu, ambazo huchukua takriban sekunde 1–2 zaidi. max ni kwa sauti ngumu zaidi na lugha nadra; kila jibu huchukua sekunde 3–4, na simu hutumia akili ya pro (intelligence hupuuzwa). max haipatikani kwa ujumla: kwa shirika ambalo haijawashwa, simu hutumia plus na intelligence unayotaja (ombi la simu inayotoka lenye thamani hii hukataliwa kwa 400). Thamani za zamani lean (Nafuu), hearing (Plus) na deep_hearing (Max) bado zinakubaliwa. Bidhaa nyingine huipuuza |
endpointing | string | null | hapana | faster (milisekunde 200), fast (milisekunde 300), normal (milisekunde 500, chaguo-msingi) au patient (milisekunde 800); null ni sawa na normal. Muda ambao ejenti ya Bolt v2 husubiri baada ya mpigaji simu kuacha kuzungumza kabla ya kuiomba modeli jibu. Kusubiri kwa muda mfupi kunaweza kujibu mapema lakini hutuma maombi zaidi ambayo maneno yanayofuata ya mpigaji simu huyafanya yasiwe tena sahihi, jambo linaloongeza gharama ya modeli. Bidhaa nyingine huipuuza |
eagerness | string | null | hapana | Imeondolewa: jina la endpointing hadi Oktoba 19, 2026, lakini bado husomwa. Hupuuzwa wakati endpointing imewekwa |
intelligence | string | null | hapana | core au pro (chaguo-msingi); null ni sawa na pro. Jinsi ejenti ya bolt kwenye mfumo wa Bolt v2 inavyofuata maelekezo yake kwa uaminifu. core huchukua takriban milisekunde 700 hadi neno la kwanza, ni ya bei nafuu zaidi na ina uaminifu mdogo kidogo (kwenye simu zinazoshughulikiwa kama PHI, takriban milisekunde 900 na uaminifu mdogo zaidi); pro huchukua takriban milisekunde 900; majibu ya Core ambayo yangeita zana pekee hukabidhiwa kwa Pro. Thamani za zamani lite (Core) na standard (Pro) bado zinakubaliwa, na plus na max zilizoondolewa hutumika kwenye pro. Hupuuzwa wakati audio_tier ni max. Bidhaa nyingine huipuuza |
faster_replies | boolean | null | hapana | Ongezeko la kasi. Chaguo-msingi ni true. Kwenye ejenti ya bolt katika mfumo wa Bolt v2, majibu huanza mapema kidogo, kwa gharama ya ziada kidogo. false huzima hilo. Bidhaa nyingine huipuuza |
background_track | string | null | hapana | Kitambulisho cha sauti ya mazingira au null |
acknowledgement_prompt_mode | string | hapana | auto (chaguo-msingi) au manual (thamani za zamani za bidhaa za -with-ack) |
acknowledgement_prompt | string | hapana | Hutumika wakati acknowledgement_prompt_mode="manual" |
silence_interval_seconds | integer | null | hapana | 5–120. Sekunde za ukimya wa mpigaji simu kabla ya ukaguzi |
silence_max_checkins | integer | null | hapana | 1–10 |
silence_checkins_enabled | boolean | hapana | Chaguo-msingi ni true |
silence_final_action | string | hapana | Baada ya ukaguzi wa mwisho: hang_up (chaguo-msingi) au transfer hadi silence_transfer_destination |
silence_transfer_destination | string | hapana | Jina la ingizo katika transfer_destinations za usanidi huu; linahitajika pamoja na transfer. Bila transfer_destinations, uhamisho hauwezi kufanywa na ejenti hukata simu |
silence_final_message | string | hapana | ≤ herufi 300, husomwa kama ilivyoandikwa; "" (chaguo-msingi) hutumia sentensi chaguo-msingi |
connect_tone_enabled | boolean | hapana | Chaguo-msingi ni false |
pronunciation_dicts | boolean | null | hapana | Chaguo-msingi ni false; null ni sawa na false. Ikiwa true, usemi wa Cartesia wa simu hutumia kamusi ya matamshi ya ThunderPhone kwa lugha ya simu, pale inapopatikana. Hufanya kazi kwa simu na simu za wijeti. Hutumika tu kwa sauti za Cartesia za ThunderPhone, si sauti zinazotumia ufunguo wako mwenyewe wa API wa Cartesia. Haitumiki pamoja na agent_id, ambapo mipangilio ya ejenti iliyohifadhiwa hutumika |
words | array | null | hapana | Jinsi ejenti inavyotamka maneno mahususi, maingizo sawa na words za ejenti bila support. Ingizo lisilo na language hutumia lugha ya usanidi huu. null na [] zinamaanisha hakuna. Haitumiki pamoja na agent_id, ambapo maneno ya ejenti yaliyohifadhiwa hutumika |
voicemail_action | string | hapana | prompt (chaguo-msingi), hangup, au message |
voicemail_message | string | hapana | Hutumika wakati voicemail_action="message" |
agent_name | string | hapana | Jina la kuonyesha linaloripotiwa kwa dashibodi na wijeti |
org_name | string | hapana | Jina la kuonyesha la shirika kwa persona ya ejenti |
tools | array | hapana | Skima za zana za utendakazi za moja kwa moja (tazama Zana za Utendakazi) |
transfer_destinations | array of object | null | hapana | Hadi maingizo 50 ya {name, number} ambayo simu hii inaweza kuhamisha kwenda, yakithibitishwa kama namba za uhamisho za ejenti. Ejenti huhamisha kwa jina na kwa hizi pekee; [] inamaanisha hakuna uhamisho. Iache au tuma null ili kuruhusu ejenti kuhamisha hadi namba inayoichagua |
timezone | string | hapana | Ukanda wa saa wa IANA kwa simu hii, kama America/Chicago. Ejenti hutaja tarehe na saa katika ukanda huo, badala ya ukanda wa saa wa ejenti mwenyewe. Pia inaruhusiwa kando ya agent_id. Thamani ambazo si kanda za IANA hupuuzwa. Tazama Weka ukanda wa saa kwa kila simu |
context | string | null | hapana | Maandishi huru ya simu hii, kama maelezo yaliyokusanywa na mfumo wako, hadi herufi 20,000. Huongezwa baada ya prompt katika kizuizi chenye vikomo na hayawasilishwi kama kiolezo. Pia inaruhusiwa kando ya agent_id. Thamani ambayo si string, au ni ndefu zaidi, hukataa simu. Tazama vigeu vya simu na muktadha |
call_id | integer | hapana | Mwangwi wa hiari wa kitambulisho cha simu cha ombi; hupuuzwa |
Kwa kuwa prompt na voice zinahitajika, kurejesha {} au jibu lolote lisilofaulu uthibitishaji kunakataa simu: simu ya simu hukatishwa kama ilivyoelezwa katika Vipindi vya kuisha na kujaribu tena, na ombi la kipindi cha wijeti hushindwa kwa 422. Hii inatumika pia kwa wapigaji wanaorudia: kitu chochote cha JSON ambacho webhook yako inarejesha ni jibu lake, na {} ndiyo njia ya kukataa simu.
Webhook ya usanidi wa simu wa ejenti
Ejenti inaweza kuwa na webhook yake ya usanidi wa simu: sehemu ya Webhook ya usanidi wa simu
katika mipangilio yake, au call_setup_webhook_url
katika API. Mpe ejenti namba, na kabla ya kila simu inayoingia
kwenye namba hiyo inayojibiwa na ejenti, ThunderPhone huuliza webhook vigeu na muktadha
wa simu hiyo. Namba huhifadhi ejenti yake, hivyo ukurasa wa namba za simu na ukurasa wa ejenti huonyesha ejenti
anayeijibu.
Huu ni mpangilio kama mingine ya ejenti: huandaliwa kama rasimu, huchapishwa wakati wa
kutuma, na huhifadhiwa katika historia ya matoleo. Namba
iliyofungwa kwenye toleo la zamani
huomba URL ya toleo hilo. Maombi husainiwa kwa siri ya ejenti mwenyewe ya
call_setup_webhook_signing_secret (si siri ya webhook ya shirika), kwa kutumia kichwa kilekile cha
X-ThunderPhone-Signature, muda wa kusubiri, kujaribu tena na ufunguo wa kutorudia kama hapo juu. Siri hii
ni ya kuandika pekee: weka siri ambayo endpoint yako hukagua (katika mipangilio ya ejenti, au kwa
PATCH /v1/agents/{id}); hakuna usomaji unaoirudisha, na
call_setup_webhook_signing_secret_set husema ikiwa ipo.
Ombi ni payload ya telephony.incoming hapo juu pamoja na ejenti
inayojazwa:
{
"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
}
}
}| Sehemu | Aina | Maelezo |
|---|---|---|
agent.id | namba kamili | Ejenti aliyowekwa kwenye namba |
agent.name | mfuatano | Jina lake |
agent.version | namba kamili | null | Namba ya toleo litakalojibu: toleo lililofungwa la namba, au toleo la hivi karibuni lililochapishwa la ejenti (null ikiwa hana lolote) |
agent.version_pinned | mantiki | Ikiwa namba imefungwa kwenye toleo hilo |
Jibu kwa kile simu inahitaji. Yoyote kati ya haya hujaza ejenti aliyowekwa, kwenye toleo la namba:
{"variables": {...}},{"context": "..."}, au vyote viwili- hali hiyo hiyo huku
"agent_id"ikiwekwa kuwa kitambulisho cha ejenti aliyowekwa {}: ejenti hujibu bila chochote kujazwa
timezone na language pia zinaruhusiwa, kama kando ya
agent_id. Vigeu hujaza
{{placeholders}} za ejenti; muktadha huongezwa baada ya prompt.
Au amua simu mwenyewe. agent_id ya ejenti mwingine, au
usanidi kamili wenye prompt, hujibu simu hii moja badala ya
ejenti aliyowekwa (na toleo lake lililofungwa). Maelezo ya simu hutambulisha kila hali katika
call_setup_webhook: assigned_agent,
other_agent au inline_config. Jibu lisiloweza kutumika (agent_id
isiyojulikana, funguo nyingine kando ya variables, usanidi
unaoshindwa uthibitishaji) hukatisha simu kama webhook ya namba.
Wakati webhook lazima ijibu. Ejenti inahitaji webhook yake wakati
mipangilio yake inatumia {{variable}} isiyo na chaguo-msingi: prompt yake au
maagizo yanayotumika tena, maagizo au mistari ya hatua, prompt ya uthibitisho,
ujumbe wa barua ya sauti, tangazo la ridhaa, au namba ya kuhamisha yenye {{variable}}.
call_setup_webhook_variables za ejenti huziorodhesha.
- Inahitaji webhook: webhook inapoishiwa muda wa kusubiri, haiwezi
kufikiwa, au inajibu kwa hitilafu au mwili ambao si kitu cha JSON,
simu haianzi, hata ikiwa simu tayari ina thamani ya
kigeu kimoja kati ya hivyo. Hukomeshwa na kurekodiwa sawasawa na ilivyoelezwa
katika Muda wa kusubiri na kujaribu tena (
end_reasoninbound_config_webhook_failed, haitozwi). - Haihitaji chochote (hakuna vigeu, au kila kimoja kina chaguo-msingi kama
{{first_name|there}}): webhook bado huendeshwa, lakini inaposhindwa ejenti hujibu bila hiyo, na maelezo ya simu huonyeshawebhook_failedpamoja na kilichoharibika.
Muktadha wa simu pekee hauwahi kufanya webhook ihitajike: hakuna chochote katika mipangilio ya ejenti kinachosema inahitaji muktadha. Tumia kigezo kisicho na chaguo-msingi ikiwa simu haipaswi kuanza bila jibu la webhook yako.
Kukabidhi na kutekeleza. Ejenti inayohitaji webhook yake haiwezi
kukabidhiwa kwa nambari isiyo na webhook: ukabidhi huo unakataliwa kwa
ujumbe unaotaja vigezo. Ukaguzi huohuo hutekelezwa wakati toleo la nambari
linapobadilika, ikijumuisha nambari iliyofungwa kurudi kwenye Toleo jipya zaidi. Wakati inajibu nambari kwa kutumia
mipangilio yake iliyochapishwa, utekelezaji unaoongeza kigezo kama hicho bila webhook
(au kuondoa webhook) unakataliwa kwa njia hiyohiyo. Kuhifadhi rasimu
kunaruhusiwa kila wakati, na warnings za ejenti hubeba
call_setup_webhook_needed hadi tatizo litakaporekebishwa.
Webhook ya ejenti hutekelezwa tu kwa simu za simu zinazoingia kwenye nambari ilizokabidhiwa. Simu zinazotoka, vipindi vya wijeti ya wavuti, anwani za SIP, uigaji na mazungumzo ya majaribio ya dashibodi haziitumii; hupata vigezo vyake kutoka kwenye ombi kama ilivyokuwa awali.
Kujaribu kwa sampuli zilizohifadhiwa. Ili kujaribu ejenti wako hufanya nini kwa jibu fulani (mpigaji anayerudi, rekodi haikupatikana, mzungumzaji wa Kihispania), hifadhi jibu hilo kwenye ejenti kama sampuli: variables, context zake na kwa hiari language, zilizoandikwa au kunakiliwa kutoka simu ya awali. Ichague unapoanzisha mazungumzo ya majaribio kwenye dashibodi, simu ya majaribio kwa simu yako au uigaji dhidi ya ejenti, na simu itaendeshwa kana kwamba webhook yako ilijibu nayo. Sampuli zinashirikiwa na kila toleo la ejenti. Kuhariri sampuli huhifadhi matoleo yake ya awali: mabadiliko ya ejenti yanapohitaji kigeu ambacho sampuli haijaweka, kiongeze kwenye sampuli, na matoleo ya zamani ya ejenti yataendelea kutumia sampuli kama ilivyokuwa. Uigaji unaopiga nambari ya simu huendesha webhook yako halisi badala yake.
Nambari zisizo na ejenti iliyokabidhiwa zinaendelea kutumia webhook ya nambari au ya shirika kama ilivyoelezwa hapo juu.
Simu za kurudia
Watu mara nyingi hupiga tena nambari iliyowapigia, kwa mfano baada ya ejenti wako kuacha ujumbe wa sauti. Simu inapoingia kutoka kwa mtu ambaye nambari hiyohiyo ilipigiwa ndani ya siku 30 zilizopita, ThunderPhone hupata simu ya hivi karibuni zaidi ya kutoka (ile iliyolia kwenye simu yao) na kuitumia kwa njia tatu:
-
returning_callkatika ombi. Ombi la kuzuia hapo juu, na arifa ya endpoint, hubeba taarifa hii, hivyo handler yako inaweza kuelekeza mpigaji:{ "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" } } }Sehemu Aina Maelezo call_idinteger Simu ya awali ya kutoka agent_idinteger | null Ejenti aliyeipiga; nullkwa simu iliyopigwa kwa config ya ndani au ambayo ejenti wake alifutwastarted_atstring Ilipoanza (ISO 8601, UTC) outcomestring no_answer(iliita bila kujibiwa, laini ilikuwa na shughuli au simu ilikataliwa),voicemail(ujumbe wa sauti ulijibu, au hakuna aliyezungumza na ejenti),conversation(mtu alizungumza na ejenti) auanswered(ilijibiwa; bado haijulikani aliyejibu) -
Muktadha kwa ejenti. Ejenti yeyote anayejibu hupata dokezo fupi mwishoni mwa prompt yake: simu ya awali ilipigwa lini, na ejenti gani, pamoja na matokeo yake. Ejenti huagizwa asilisome kwa sauti, na, kwa kuwa kitambulisho cha mpigaji kinaweza kughushiwa, asishiriki chochote kuhusu simu hiyo isipokuwa kwamba nambari hiyo iliwahi kupigiwa.
-
Ejenti mbadala. Nambari inapokuwa haina ejenti wa simu zinazoingia na hakuna usanidi unaowasili kwa sababu hakuna URL ya webhook au webhook yako haikutoa jibu (iliishiwa muda, haikuweza kufikiwa, au ilijibu
5xx,408au429katika majaribio yote mawili), simu huenda kwa ejenti aliyepiga simu ya awali badala ya kukatwa, mradi ejenti huyo bado yupo katika shirika lako. Huendeshwa kwa mipangilio iliyotumwa ya ejenti huyo. Jibu lolote ambalo webhook yako hutoa bado huamua:4xxnyingine, body ambayo si JSON object,{}, au config inayoshindwa uthibitishaji hukata simu kama ilivyokuwa awali. Ejenti wa simu zinazoingia kwenye nambari hujibu kila wakati.
Kushiriki maelezo ya simu ya awali. Kitambulisho cha mpigaji kinaweza
kughushiwa, kwa hivyo kwa chaguo-msingi hakuna maudhui kutoka simu ya awali
yanayofikia simu mpya. Msimamizi wa shirika anaweza kuwasha Shiriki maelezo ya simu ya awali
chini ya Organization → General → Callbacks (au kuweka
callback_context_details_enabled).
Ikiwashwa, dokezo la ejenti pia hunukuu muhtasari wa simu ya awali, na simu
inayoelekezwa kwa ejenti aliyepiga simu ya awali huendeshwa kwa variables za
simu hiyo (kama vile jina la mwasiliani). Iwashe tu ikiwa maelezo hayo ni salama
kushirikiwa na yeyote anayepiga kutoka nambari hiyo. Hata ikiwa imewashwa, simu
ambayo inaweza kuwa na taarifa za afya zinazolindwa haiwahi kupitisha muhtasari
au variables zake kwa simu ambayo haijateuliwa kuchakata PHI.
Katika maelezo ya simu. Simu inayoingia iliyolingana na simu ya awali ina
kitu cha callback katika GET /v1/calls/{call_id}:
returning_call iliyo hapo juu, routed_as_callback (iwapo njia mbadala
iliijibu), na config_webhook_failure ({kind, attempts, http_status, host} wakati webhook yako haikutoa jibu na njia mbadala ilipokea
simu, vinginevyo null), ili hitilafu ya webhook ibaki kuonekana hata kama
simu ilijibiwa.
Kikomo cha ukubwa wa jibu
Mfano wa kishughulikiaji
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({});
},
);Jibu lenye zana za function
Ambatisha zana ili ejenti AI iweze kuita API zako katikati ya mazungumzo:
{
"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"
}
}
}
]
}Muhtasari wa haraka wa mipangilio
Tuma product: "bolt" na urekebishe simu kwa kutumia sehemu hizi. Thamani za zamani za
product (spark na thamani za storm-*) bado zinakubaliwa.
| Sehemu | Thamani | Kinachobadilishwa |
|---|---|---|
intelligence | core, pro (chaguo-msingi) | Core ni nafuu zaidi na huanza kujibu mapema; Pro hufuata prompt ndefu kwa uaminifu zaidi |
audio_tier | lite, standard (chaguo-msingi), plus, max | Viwango vya juu husikia vizuri zaidi na hugharimu zaidi; Plus huongeza 1–2 s katika baadhi ya zamu, kila jibu la Max huchukua 3–4 s (Max haipatikani kwa ujumla) |
endpointing | faster, fast, normal (chaguo-msingi), patient | Kusubiri kwa muda mfupi hujibu mapema na hugharimu zaidi |
faster_replies | true (chaguo-msingi), false | Ongezeko la kasi: majibu huja mapema kidogo, kwa gharama zaidi kidogo |
Yanayohusiana
Tukio lisilozuia la mwisho wa simu.
Schemata kamili ya JSON ya tools[] na mkataba wa endpoint uliotiwa sahihi.
Jiandikishe URL nyingi kwa telephony.incoming / web.incoming.
Miundo ya prompt, zana na majaribio ya A/B kwa kila mpigaji.