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

Webhooks

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, 408 au 429, 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, au 2xx ambayo mwili wake si usanidi halali ni la mwisho na halijaribiwi tena.
  • Majaribio yote mawili hutuma mwili uleule, X-ThunderPhone-Signature ileile, na kichwa kilekile cha X-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"
  }
}
SehemuAinaMaelezo
call_idintegerKitambulisho cha simu — thabiti katika matukio yote ya simu hii
from_numberstringNamba ya mpigaji katika E.164
to_numberstringLengwa la E.164 (moja ya namba zako za ThunderPhone)
returning_callobjectHupo tu wakati namba hii ilimpigia mpigaji ndani ya siku 30 zilizopita. Tazama Simu za kurudia
sip_headersobjectHupo 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"
  }
}
SehemuAinaMaelezo
call_idintegerKitambulisho cha simu
origin_domainstringAsili 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_prefixstringHerufi za kwanza za ufunguo unaoweza kuchapishwa uliofungua kipindi
language, primary_languagestringHupo wakati kipindi cha wijeti kilipoomba ubatilishaji wa lugha
voicestringHupo wakati kipindi cha wijeti kilipoomba ubatilishaji wa sauti
website_contextstringHupo 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":   []
}
SehemuAinaInahitajikaMaelezo
promptstringndiyoPrompt ya mfumo inayoongoza ejenti
voicestringndiyoKitambulisho cha sauti kutoka GET /v1/voices, kwa mfano john. voice_name inakubaliwa kama jina mbadala. Sauti zisizojulikana hushindwa uthibitishaji na kukataa simu
productstringhapanaTuma 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_levelstringhapanaminimal, base (chaguo-msingi), au extra. Kwenye thamani za bidhaa za zamani za storm-*, storm-extra* hulazimisha extra na storm-* nyingine hulazimisha base
audio_context_modestringhapanafull (chaguo-msingi) au reduced
watchdog_enabledbooleanhapanaWasha usimamizi kwa simu hii. Chaguo-msingi ni false
additional_audio_contextboolean | nullhapanaJumuisha 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_modestringhapananone, acknowledgement (chaguo-msingi), au tick: kile mpigaji simu husikia wakati jibu la polepole zaidi linatayarishwa ikiwa audio_tier ni plus au max
languagestringhapanaUfupisho 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_languagestringhapanaMsimbo wa lugha, uliosanifishwa (chaguo-msingi en). Misimbo isiyoweza kutatuliwa hukataa simu
has_additional_languagesbooleanhapanaChaguo-msingi ni false
additional_languagesarray of stringhapanaLugha za ziada ambazo ejenti inaweza kubadilisha kwenda
native_voice_switchingbooleanhapanaChaguo-msingi ni false. Simu inapobadilisha hadi lugha nyingine, badilisha hadi sauti asilia ya lugha hiyo (inayolingana kwa jinsia) badala ya kuhifadhi sauti iliyosanidiwa
language_switchingstring | nullhapanaask_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_tierstring | nullhapanaKwa 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
endpointingstring | nullhapanafaster (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
eagernessstring | nullhapanaImeondolewa: jina la endpointing hadi Oktoba 19, 2026, lakini bado husomwa. Hupuuzwa wakati endpointing imewekwa
intelligencestring | nullhapanacore 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_repliesboolean | nullhapanaOngezeko 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_trackstring | nullhapanaKitambulisho cha sauti ya mazingira au null
acknowledgement_prompt_modestringhapanaauto (chaguo-msingi) au manual (thamani za zamani za bidhaa za -with-ack)
acknowledgement_promptstringhapanaHutumika wakati acknowledgement_prompt_mode="manual"
silence_interval_secondsinteger | nullhapana5–120. Sekunde za ukimya wa mpigaji simu kabla ya ukaguzi
silence_max_checkinsinteger | nullhapana1–10
silence_checkins_enabledbooleanhapanaChaguo-msingi ni true
silence_final_actionstringhapanaBaada ya ukaguzi wa mwisho: hang_up (chaguo-msingi) au transfer hadi silence_transfer_destination
silence_transfer_destinationstringhapanaJina la ingizo katika transfer_destinations za usanidi huu; linahitajika pamoja na transfer. Bila transfer_destinations, uhamisho hauwezi kufanywa na ejenti hukata simu
silence_final_messagestringhapana≤ herufi 300, husomwa kama ilivyoandikwa; "" (chaguo-msingi) hutumia sentensi chaguo-msingi
connect_tone_enabledbooleanhapanaChaguo-msingi ni false
pronunciation_dictsboolean | nullhapanaChaguo-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
wordsarray | nullhapanaJinsi 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_actionstringhapanaprompt (chaguo-msingi), hangup, au message
voicemail_messagestringhapanaHutumika wakati voicemail_action="message"
agent_namestringhapanaJina la kuonyesha linaloripotiwa kwa dashibodi na wijeti
org_namestringhapanaJina la kuonyesha la shirika kwa persona ya ejenti
toolsarrayhapanaSkima za zana za utendakazi za moja kwa moja (tazama Zana za Utendakazi)
transfer_destinationsarray of object | nullhapanaHadi 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
timezonestringhapanaUkanda 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
contextstring | nullhapanaMaandishi 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_idintegerhapanaMwangwi 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
    }
  }
}
SehemuAinaMaelezo
agent.idnamba kamiliEjenti aliyowekwa kwenye namba
agent.namemfuatanoJina lake
agent.versionnamba kamili | nullNamba ya toleo litakalojibu: toleo lililofungwa la namba, au toleo la hivi karibuni lililochapishwa la ejenti (null ikiwa hana lolote)
agent.version_pinnedmantikiIkiwa 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_reason inbound_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 huonyesha webhook_failed pamoja 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:

  1. returning_call katika 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"
        }
      }
    }
    SehemuAinaMaelezo
    call_idintegerSimu ya awali ya kutoka
    agent_idinteger | nullEjenti aliyeipiga; null kwa simu iliyopigwa kwa config ya ndani au ambayo ejenti wake alifutwa
    started_atstringIlipoanza (ISO 8601, UTC)
    outcomestringno_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) au answered (ilijibiwa; bado haijulikani aliyejibu)
  2. 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.

  3. 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, 408 au 429 katika 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: 4xx nyingine, 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

Python (FastAPI)
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 {}
Node.js (Express)
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.

SehemuThamaniKinachobadilishwa
intelligencecore, pro (chaguo-msingi)Core ni nafuu zaidi na huanza kujibu mapema; Pro hufuata prompt ndefu kwa uaminifu zaidi
audio_tierlite, standard (chaguo-msingi), plus, maxViwango 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)
endpointingfaster, fast, normal (chaguo-msingi), patientKusubiri kwa muda mfupi hujibu mapema na hugharimu zaidi
faster_repliestrue (chaguo-msingi), falseOngezeko la kasi: majibu huja mapema kidogo, kwa gharama zaidi kidogo

Yanayohusiana