ThunderPhone v3 พร้อมให้ใช้งานแล้วเริ่มใช้งานได้ด้วยตัวเอง ราคาเริ่มต้น 2 เซนต์ต่อนาที.อ่านประกาศเปิดตัว

Webhooks

telephony.incoming / web.incoming

เว็บฮุกแบบบล็อกที่กำหนดการตั้งค่าของสายเรียกเข้าแบบเรียลไทม์

เมื่อสายโทรศัพท์ขาเข้าไปถึงหมายเลขที่ยังไม่ได้กำหนด เอเจนต์ (ดูการโทรกลับสำหรับผู้โทรที่โทรกลับจากสาย ขาออกของคุณ) หรือเซสชันวิดเจ็ตเว็บเริ่มต้นบนคีย์ที่เผยแพร่ได้ใน mode="webhook" ThunderPhone จะส่งคำขอแบบบล็อก telephony.incoming / web.incomingไปยัง URL เว็บฮุกแบบเดิม ของคุณ และรอการตอบกลับการกำหนดค่า: สูงสุด13 วินาทีสำหรับ สายโทรศัพท์ รวมการลองใหม่หนึ่งครั้ง และสูงสุด10 วินาทีสำหรับ เซสชันวิดเจ็ต (ดูการหมดเวลาและการลองใหม่) ใช้ การแลกเปลี่ยนนี้เพื่อเลือกพรอมต์ เสียง และเครื่องมือแบบไดนามิกสำหรับแต่ละสาย — ดูรูปแบบตั้งแต่ต้นจนจบได้ที่ คู่มือการกำหนดค่าสายแบบไดนามิก

หมายเลขที่มีเอเจนต์ที่กำหนดไว้จะรับสายด้วยเอเจนต์นั้น เมื่อ เอเจนต์มีเว็บฮุกการตั้งค่าสายของตนเอง ระบบจะดำเนินการแลกเปลี่ยนแบบบล็อกเดียวกันก่อนที่ URL ของเอเจนต์ เพื่อเติมตัวแปรของเอเจนต์และบริบทของสาย

การหมดเวลาและการลองใหม่

ตอบกลับอย่างรวดเร็ว: ผู้โทรกำลังรอสายอยู่ขณะที่คุณตัดสินใจ

สำหรับการโทรศัพท์ (telephony.incoming):

  • การลองครั้งแรกอาจใช้เวลาสูงสุด 10 วินาที
  • หากหมดเวลา เชื่อมต่อไม่ได้ หรือได้รับการตอบกลับ 5xx, 408 หรือ 429 ThunderPhone จะลองอีกครั้ง การลองใหม่จะได้รับเวลาที่เหลือจากงบเวลา 13 วินาที สำหรับการแลกเปลี่ยนทั้งหมด: ประมาณ 3 วินาทีหลังจากการลองครั้งแรกหมดเวลา หรือเกือบครบ 13 วินาทีหลังจากความล้มเหลวอย่างรวดเร็ว จะไม่มีการลองใหม่หากเหลือเวลาน้อยกว่า 2 วินาที
  • การตอบกลับ 4xx อื่น ๆ การตอบกลับที่เกิน ขีดจำกัดขนาด หรือ 2xx ที่เนื้อหาไม่ใช่การกำหนดค่าที่ถูกต้อง ถือเป็นผลลัพธ์สุดท้ายและจะไม่ลองใหม่
  • ทั้งสองการลองจะส่งเนื้อหาเดียวกัน X-ThunderPhone-Signature เดียวกัน และส่วนหัว X-ThunderPhone-Idempotency-Key เดียวกัน (telephony-incoming-<call_id>) ดังนั้นตัวจัดการที่มีผลข้างเคียงจึงสามารถตรวจจับการลองใหม่ได้

หากไม่มีการกำหนดค่าที่ใช้ได้มาถึง ระบบจะยุติการโทรทันที แทนที่จะปล่อยให้ผู้โทรอยู่บนสายที่เงียบ การโทรจะแสดงใน ประวัติการโทรเป็นการโทรที่ล้มเหลวและไม่มีการคิดค่าบริการ โดยมี end_reason เป็น inbound_config_webhook_failed และมีการส่งเหตุการณ์ telephony.complete ตามปกติ หน้าของการโทร ในแดชบอร์ด และ config_webhook_failure ใน GET /v1/calls/{call_id} จะระบุสิ่งที่เว็บฮุก ของคุณดำเนินการ: {kind, attempts, http_status, host, source} โดย kind คือ http_error, timeout, connection, dns, tls, response_too_large, blocked_url, other, invalid_json, non_object_json หรือ invalid_config, host คือชื่อโฮสต์ของเว็บฮุกคุณ และ source คือ number (เว็บฮุกนี้) หรือ agent_setup (เว็บฮุกตั้งค่าการโทรของเอเจนต์) สำหรับ invalid_config ค่า reason จะระบุสาเหตุที่ไม่สามารถใช้คำตอบได้ และ fields จะระบุชื่อฟิลด์ที่เกี่ยวข้อง: no_agent (ไม่มีทั้ง agent_id และ prompt; fields จะแสดงรายการคีย์ที่ถูกละเว้น เช่น agentId ที่สะกดผิด), agent_not_found, agent_id_not_integer, unexpected_fields (คีย์อื่นนอกเหนือจาก variables, context, timezone และ language ที่อยู่ร่วมกับ agent_id), invalid_variables, invalid_context, invalid_language, unsupported_language, invalid_config_fields หรือ agent_settings_invalid ในกรณีอื่น reason จะเป็น null และ fields จะว่างเปล่า ข้อยกเว้น เพียงกรณีเดียวคือผู้โทรโทรกลับมายังการโทรขาออกสายหนึ่งของคุณ เมื่อ กระบวนการแลกเปลี่ยนเองล้มเหลว: ดู การโทรกลับ

เซสชันวิดเจ็ต (web.incoming) จะได้รับการลองเพียงครั้งเดียวสูงสุด 10 วินาที หากล้มเหลว คำขอเซสชันจะล้มเหลวด้วย 502 หรือ 422

เพย์โหลดคำขอ

สำหรับสายโทรศัพท์ (telephony.incoming):

{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567"
  }
}
ฟิลด์ประเภทคำอธิบาย
call_idจำนวนเต็มรหัสการโทร — คงเดิมตลอดทุกเหตุการณ์ของการโทรนี้
from_numberสตริงหมายเลขผู้โทรในรูปแบบ E.164
to_numberสตริงปลายทาง E.164 (หนึ่งในหมายเลข ThunderPhone ของคุณ)
returning_callออบเจ็กต์มีเฉพาะเมื่อหมายเลขนี้โทรหาผู้โทรภายใน 30 วันที่ผ่านมา ดู การโทรกลับ
sip_headersออบเจ็กต์มีเฉพาะเมื่อสายเรียกเข้าผ่านการเชื่อมต่อ SIP แบบกำหนดเองพร้อมส่วนหัว SIP X-* หรือ User-to-User: ชื่อส่วนหัวเป็นตัวพิมพ์เล็ก → ค่า ดู ส่วนหัว SIP

สำหรับเซสชันวิดเจ็ตเว็บ (web.incoming) data จะระบุหน้าที่ฝังวิดเจ็ต แทนหมายเลขโทรศัพท์:

{
  "type": "web.incoming",
  "data": {
    "call_id": 987654322,
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2"
  }
}
ฟิลด์ประเภทคำอธิบาย
call_idจำนวนเต็มรหัสการโทร
origin_domainสตริงต้นทางของหน้าที่โฮสต์วิดเจ็ต ตามที่เบราว์เซอร์ส่งมา ไคลเอนต์ที่ไม่ใช่เบราว์เซอร์สามารถส่งค่าใดก็ได้ ดังนั้นอย่าถือว่านี่เป็นหลักฐานว่าคำขอมาจากที่ใด
publishable_key_prefixสตริงอักขระแรกของคีย์เผยแพร่ที่เปิดเซสชัน
language, primary_languageสตริงมีอยู่เมื่อเซสชันวิดเจ็ตร้องขอการแทนที่การตั้งค่าภาษา
voiceสตริงมีอยู่เมื่อเซสชันวิดเจ็ตร้องขอการแทนที่การตั้งค่าเสียง
website_contextสตริงมีอยู่เมื่อวิดเจ็ตส่งบริบทของหน้าสำหรับแต่ละเซสชัน

ฟิลด์การแทนที่ (language, voice, website_context และ variables ของเบราว์เซอร์) จะมาถึงเฉพาะเมื่อคีย์เผยแพร่อนุญาตใน การแทนที่จากเบราว์เซอร์ คำขอ เซสชันที่มีฟิลด์ซึ่งคีย์ไม่อนุญาตจะถูกปฏิเสธก่อนที่จะเรียก เว็บฮุกนี้


สคีมาการตอบกลับ

ส่งคืนออบเจ็กต์ JSON ที่อธิบายการกำหนดค่าเอเจนต์สำหรับการโทรนี้ ต้องระบุ prompt และ voice; ส่วนอื่นทั้งหมดเป็นตัวเลือก

{
  "prompt":  "You are a helpful booking assistant for Acme Restaurant.",
  "voice":   "john",
  "product": "spark",
  "background_track": null,
  "tools":   []
}
ฟิลด์ประเภทจำเป็นคำอธิบาย
promptstringใช่พรอมต์ระบบที่กำหนดการทำงานของเอเจนต์
voicestringใช่รหัสเสียงจาก GET /v1/voices เช่น john ยอมรับ voice_name เป็นชื่อแทนได้ เสียงที่ไม่รู้จักจะไม่ผ่านการตรวจสอบและปฏิเสธสาย
productstringไม่ส่ง bolt ค่าเริ่มต้นคือ spark ซึ่งเป็นค่าเก่าที่ยังคงรองรับร่วมกับ storm-base, storm-base-with-ack, storm-extra และ storm-extra-with-ack
thinking_levelstringไม่minimal, base (ค่าเริ่มต้น) หรือ extra สำหรับค่าผลิตภัณฑ์ storm-* แบบเก่า storm-extra* จะบังคับใช้ extra และ storm-* อื่นจะบังคับใช้ base
audio_context_modestringไม่full (ค่าเริ่มต้น) หรือ reduced
watchdog_enabledbooleanไม่เปิดใช้การกำกับดูแลสำหรับสายนี้ ค่าเริ่มต้นคือ false
additional_audio_contextboolean | nullไม่รวมเสียงของผู้โทรในช่วงไม่กี่เทิร์นล่าสุด แทนที่จะรวมเฉพาะเทิร์นล่าสุด ช่วยปรับปรุงการแก้ไขและการเก็บข้อมูลที่มีการสะกด/ตัวเลขจำนวนมาก โดยเพิ่มเวลาแฝง/ค่าใช้จ่ายเล็กน้อย ค่าเริ่มต้นเปิดสำหรับเซสชันขาเข้าและปิดสำหรับการโทรออก null จะคงค่าเริ่มต้นไว้
storm_feedback_modestringไม่none, acknowledgement (ค่าเริ่มต้น) หรือ tick: สิ่งที่ผู้โทรได้ยินขณะกำลังประมวลผลคำตอบที่ช้ากว่า เมื่อ audio_tier เป็น plus หรือ max
languagestringไม่ชื่อย่อของ primary_language ใช้ร่วมกับ agent_id ได้เช่นกัน โดยเป็นภาษาที่สายนี้เริ่มต้นด้วย ซึ่งเอเจนต์จะพูดด้วยเสียงที่กำหนดไว้สำหรับภาษานั้น ดู ตั้งค่าภาษาสำหรับแต่ละสาย
primary_languagestringไม่รหัสภาษา ที่ปรับรูปแบบแล้ว (ค่าเริ่มต้น en) รหัสที่ไม่สามารถระบุได้จะปฏิเสธสาย
has_additional_languagesbooleanไม่ค่าเริ่มต้นคือ false
additional_languagesarray of stringไม่ภาษาเพิ่มเติมที่เอเจนต์อาจสลับไปใช้
native_voice_switchingbooleanไม่ค่าเริ่มต้นคือ false เมื่อสายสลับไปยังภาษาอื่น ให้เปลี่ยนเป็นเสียงเจ้าของภาษาของภาษานั้น (จับคู่ตามเพศ) แทนการคงเสียงที่กำหนดค่าไว้
language_switchingstring | nullไม่ask_first (ค่าเริ่มต้น) หรือ follow_caller; null มีความหมายเดียวกับ ask_first กำหนดวิธีที่เอเจนต์หลายภาษาจัดการเมื่ออีกฝ่ายพูดภาษาอื่นที่เอเจนต์รองรับ ask_first จะสลับทันทีเมื่ออีกฝ่ายขอใช้ภาษานั้นหรือพูดเป็นประโยคเต็มในภาษานั้น และจะถามว่าต้องการดำเนินการต่อในภาษานั้นหรือไม่หลังจากคำพูดสั้น ๆ เช่น "sí" follow_caller จะสลับไปยังภาษาที่กำหนดค่าไว้ไม่ว่าผู้โทรจะพูดภาษาใด แม้เพียงคำเดียว ใช้ได้เฉพาะเมื่อตั้งค่า additional_languages
audio_tierstring | nullไม่ใช้กับ product: "bolt" เท่านั้น การรับฟัง: ระดับความละเอียดที่เอเจนต์ใช้ฟังผู้โทร standard (ค่าเริ่มต้น; "" และ null มีความหมายเดียวกัน) เหมาะกับสายส่วนใหญ่ (สายที่ประมวลผล PHI จะใช้เฉพาะผู้ให้บริการที่ครอบคลุมโดย BAA) lite มีค่าใช้จ่ายต่ำสุดและฟังผิดบ่อยกว่า plus จะฟังละเอียดขึ้นในเทิร์นที่ยาก ซึ่งใช้เวลานานขึ้นประมาณ 1–2 วินาที max สำหรับเสียงที่ยากที่สุดและภาษาที่พบไม่บ่อย ทุกคำตอบใช้เวลา 3–4 วินาที และสายจะใช้ความสามารถ pro (intelligence จะถูกละเว้น) max ไม่ได้พร้อมใช้งานทั่วไป: สำหรับองค์กรที่ยังไม่ได้เปิดใช้ สายจะทำงานด้วย plus และ intelligence ที่คุณระบุ (คำขอโทรออกที่ระบุค่านี้จะถูกปฏิเสธด้วย 400) ยังคงรองรับค่าเก่า lean (Lite), hearing (Plus) และ deep_hearing (Max) ผลิตภัณฑ์อื่นจะละเว้นค่านี้
endpointingstring | nullไม่faster (200 ms), fast (300 ms), normal (500 ms, ค่าเริ่มต้น) หรือ patient (800 ms); null มีความหมายเดียวกับ normal ระยะเวลาที่เอเจนต์ Bolt v2 รอหลังผู้โทรหยุดพูดก่อนขอคำตอบจากโมเดล การรอที่สั้นกว่าตอบได้เร็วขึ้น แต่อาจส่งคำขอเพิ่มที่คำพูดถัดไปของผู้โทรทำให้ล้าสมัย ซึ่งเพิ่มค่าใช้จ่ายของโมเดล ผลิตภัณฑ์อื่นจะละเว้นค่านี้
eagernessstring | nullไม่เลิกใช้แล้ว: ชื่อของ endpointing จนถึงวันที่ 19 ตุลาคม 2026 แต่ยังคงอ่านค่าอยู่ จะถูกละเว้นเมื่อตั้งค่า endpointing
intelligencestring | nullไม่core หรือ pro (ค่าเริ่มต้น); null มีความหมายเดียวกับ pro กำหนดความน่าเชื่อถือที่เอเจนต์ bolt บนไปป์ไลน์ Bolt v2 ปฏิบัติตามคำสั่ง core ใช้เวลาประมาณ 700 ms จนถึงคำแรก มีค่าใช้จ่ายต่ำสุดและน่าเชื่อถือน้อยกว่าเล็กน้อย (สำหรับสายที่ถือเป็น PHI ใช้เวลาประมาณ 900 ms และน่าเชื่อถือน้อยกว่า) pro ใช้เวลาประมาณ 900 ms คำตอบของ Core ที่จะเรียกใช้เพียงเครื่องมือจะถูกส่งต่อให้ Pro ยังคงรองรับค่าเก่า lite (Core) และ standard (Pro) และค่า plus กับ max ที่เลิกใช้แล้วจะทำงานบน pro จะถูกละเว้นเมื่อ audio_tier เป็น max ผลิตภัณฑ์อื่นจะละเว้นค่านี้
faster_repliesboolean | nullไม่เพิ่มความเร็ว ค่าเริ่มต้นคือ true สำหรับเอเจนต์ bolt บนไปป์ไลน์ Bolt v2 คำตอบจะเริ่มเร็วขึ้นเล็กน้อยโดยมีค่าใช้จ่ายเพิ่มขึ้นเล็กน้อย false จะปิดการทำงานนี้ ผลิตภัณฑ์อื่นจะละเว้นค่านี้
background_trackstring | nullไม่รหัสเสียงบรรยากาศหรือ null
acknowledgement_prompt_modestringไม่auto (ค่าเริ่มต้น) หรือ manual (ค่าผลิตภัณฑ์ -with-ack แบบเก่า)
acknowledgement_promptstringไม่ใช้เมื่อ acknowledgement_prompt_mode="manual"
silence_interval_secondsinteger | nullไม่5–120 จำนวนวินาทีที่ผู้โทรเงียบก่อนตรวจสอบสถานะ
silence_max_checkinsinteger | nullไม่1–10
silence_checkins_enabledbooleanไม่ค่าเริ่มต้นคือ true
silence_final_actionstringไม่หลังการตรวจสอบสถานะครั้งสุดท้าย: hang_up (ค่าเริ่มต้น) หรือ transfer ไปยัง silence_transfer_destination
silence_transfer_destinationstringไม่ชื่อของรายการใน transfer_destinations ของการกำหนดค่านี้ จำเป็นเมื่อใช้ transfer หากไม่มี transfer_destinations จะโอนสายไม่ได้และเอเจนต์จะวางสาย
silence_final_messagestringไม่≤ 300 อักขระ อ่านตามที่เขียน "" (ค่าเริ่มต้น) จะใช้ข้อความเริ่มต้น
connect_tone_enabledbooleanไม่ค่าเริ่มต้นคือ false
pronunciation_dictsboolean | nullไม่ค่าเริ่มต้นคือ false; null มีความหมายเดียวกับ false เมื่อเป็น true ระบบเสียงพูด Cartesia ของสายจะใช้พจนานุกรมการออกเสียงของ ThunderPhone สำหรับภาษาของสาย หากมี ใช้ได้กับการโทรศัพท์และวิดเจ็ต ใช้เฉพาะกับเสียง Cartesia ของ ThunderPhone ไม่ใช้กับเสียงบนคีย์ Cartesia API ของคุณเอง ไม่ใช้กับ agent_id ซึ่งจะใช้การตั้งค่าของเอเจนต์ที่บันทึกไว้
wordsarray | nullไม่วิธีที่เอเจนต์ออกเสียงคำเฉพาะ โดยใช้รายการเดียวกับ words ของเอเจนต์โดยไม่มี support รายการที่ไม่มี language จะใช้ภาษาของการกำหนดค่านี้ null และ [] หมายถึงไม่มี ไม่ใช้กับ agent_id ซึ่งจะใช้คำของเอเจนต์ที่บันทึกไว้
voicemail_actionstringไม่prompt (ค่าเริ่มต้น), hangup หรือ message
voicemail_messagestringไม่ใช้เมื่อ voicemail_action="message"
agent_namestringไม่ชื่อที่แสดงซึ่งรายงานไปยังแดชบอร์ดและวิดเจ็ต
org_namestringไม่ชื่อที่แสดงขององค์กรสำหรับบุคลิกของเอเจนต์
toolsarrayไม่สคีมาเครื่องมือฟังก์ชันแบบอินไลน์ (ดู เครื่องมือฟังก์ชัน)
transfer_destinationsarray of object | nullไม่รายการ {name, number} สูงสุด 50 รายการที่สายนี้สามารถโอนได้ โดยตรวจสอบความถูกต้องเช่นเดียวกับ หมายเลขโอนสาย ของเอเจนต์ เอเจนต์จะโอนตามชื่อและโอนได้เฉพาะรายการเหล่านี้ [] หมายถึงไม่มีการโอนสาย ละเว้นหรือส่ง null เพื่อให้เอเจนต์โอนไปยังหมายเลขที่เลือกเอง
timezonestringไม่เขตเวลา IANA สำหรับสายนี้ เช่น America/Chicago เอเจนต์จะแจ้งวันที่และเวลาในเขตเวลานั้น โดยให้ความสำคัญเหนือเขตเวลาของเอเจนต์เอง ใช้ร่วมกับ agent_id ได้เช่นกัน ค่าที่ไม่ใช่เขตเวลา IANA จะถูกละเว้น ดู ตั้งค่าเขตเวลาสำหรับแต่ละสาย
contextstring | nullไม่ข้อความอิสระสำหรับสายนี้ เช่น บันทึกที่ระบบของคุณรวบรวม ความยาวสูงสุด 20,000 อักขระ ระบบจะเพิ่มหลังพรอมต์ในบล็อกที่มีตัวคั่น และจะไม่แสดงผลเป็นเทมเพลต ใช้ร่วมกับ agent_id ได้เช่นกัน ค่าที่ไม่ใช่สตริงหรือยาวเกินกำหนดจะปฏิเสธสาย ดู ตัวแปรสายและบริบท
call_idintegerไม่การสะท้อนรหัสสายของคำขอแบบเลือกได้ จะถูกละเว้น

เนื่องจากต้องระบุ prompt และ voice การส่งคืน {} หรือการตอบกลับใดๆ ที่ไม่ผ่านการตรวจสอบจะปฏิเสธสาย: สายโทรศัพท์จะสิ้นสุดตามที่อธิบายไว้ใน การหมดเวลาและการลองใหม่ และคำขอเซสชันของวิดเจ็ตจะล้มเหลวด้วย 422 กรณีนี้ใช้กับผู้โทรที่โทรกลับด้วย: ออบเจ็กต์ JSON ใดๆ ที่ webhook ของคุณส่งคืนถือเป็นคำตอบ และ {} คือวิธีปฏิเสธสาย


เว็บฮุกการตั้งค่าการโทรของเอเจนต์

เอเจนต์สามารถมีเว็บฮุกการตั้งค่าการโทรของตนเองได้: ฟิลด์ เว็บฮุกการตั้งค่าการโทร ในการตั้งค่า หรือ call_setup_webhook_url ใน API กำหนดเอเจนต์ให้กับหมายเลข แล้วก่อนที่เอเจนต์จะตอบรับสายเรียกเข้าแต่ละสาย ของหมายเลขนั้น ThunderPhone จะขอตัวแปรและบริบทของสายนั้นจากเว็บฮุก หมายเลขจะยังคงเชื่อมโยงกับเอเจนต์เดิม ดังนั้นหน้าหมายเลขโทรศัพท์และหน้าเอเจนต์จะแสดงว่าเอเจนต์ใดเป็นผู้ตอบรับสาย

การตั้งค่านี้ทำงานเช่นเดียวกับการตั้งค่าอื่นของเอเจนต์: จัดเก็บเป็นฉบับร่าง เผยแพร่เมื่อปรับใช้ และเก็บไว้ในประวัติเวอร์ชัน หมายเลขที่ ปักหมุดไว้กับเวอร์ชันเก่า จะเรียก URL ของเวอร์ชันนั้น คำขอจะมีลายเซ็นด้วย call_setup_webhook_signing_secret ของเอเจนต์เอง (ไม่ใช่ข้อมูลลับเว็บฮุกขององค์กร) โดยใช้ส่วนหัว X-ThunderPhone-Signature การหมดเวลา การลองใหม่ และคีย์ไอดีมโพเทนซีเดียวกับด้านบน ข้อมูลลับนี้ เขียนได้อย่างเดียว: ตั้งค่าข้อมูลลับที่ปลายทางของคุณตรวจสอบ (ในการตั้งค่าของเอเจนต์ หรือด้วย PATCH /v1/agents/{id}); การอ่านข้อมูลจะไม่ส่งคืนค่านี้ และ call_setup_webhook_signing_secret_set จะระบุว่ามีการตั้งค่าไว้หรือไม่

คำขอคือเพย์โหลด telephony.incoming ด้านบน พร้อมเอเจนต์ที่จะเติมข้อมูล:

{
  "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
    }
  }
}
ฟิลด์ประเภทคำอธิบาย
agent.idintegerเอเจนต์ที่กำหนดให้กับหมายเลข
agent.namestringชื่อของเอเจนต์
agent.versioninteger | nullหมายเลขเวอร์ชันที่จะตอบรับสาย: เวอร์ชันที่หมายเลขปักหมุดไว้ หรือเวอร์ชันที่เผยแพร่ล่าสุดของเอเจนต์ (null หากไม่มี)
agent.version_pinnedbooleanหมายเลขปักหมุดไว้กับเวอร์ชันนั้นหรือไม่

ตอบด้วยสิ่งที่การโทรต้องการ ตัวเลือกใดต่อไปนี้จะเติมข้อมูลใน เอเจนต์ที่กำหนด ตามเวอร์ชันของหมายเลข:

  • {"variables": {...}}, {"context": "..."} หรือทั้งสองรายการ
  • แบบเดียวกันโดยตั้งค่า "agent_id" เป็น id ของเอเจนต์ที่กำหนด
  • {}: เอเจนต์ตอบรับสายโดยไม่มีข้อมูลที่เติมไว้

อนุญาตให้ใช้ timezone และ language ได้ด้วย เช่นเดียวกับ agent_id ตัวแปรจะเติมค่าใน {{placeholders}} ของเอเจนต์ ส่วนบริบทจะเพิ่มต่อท้ายพรอมต์

หรือกำหนดการโทรด้วยตนเอง agent_id ของเอเจนต์อื่น หรือ การกำหนดค่าแบบเต็มที่มี prompt จะใช้ตอบรับการโทรครั้งนี้แทนเอเจนต์ที่กำหนด (และเวอร์ชันที่ปักหมุดไว้) รายละเอียดการโทรจะระบุแต่ละกรณีใน call_setup_webhook: assigned_agent, other_agent หรือ inline_config การตอบกลับที่ใช้ไม่ได้ (เช่น agent_id ที่ไม่รู้จัก คีย์อื่นที่อยู่ร่วมกับ variables หรือการกำหนดค่าที่ ไม่ผ่านการตรวจสอบ) จะยุติการโทรเช่นเดียวกับเว็บฮุกของหมายเลข

เมื่อเว็บฮุกต้องตอบกลับ เอเจนต์ต้องใช้เว็บฮุกเมื่อการตั้งค่ามี {{variable}} ที่ไม่มีค่าเริ่มต้น: พรอมต์หรือคำสั่งที่ใช้ซ้ำได้ คำสั่งหรือบรรทัดของขั้นตอน พรอมต์การยืนยัน ข้อความเสียง ข้อความประกาศขอความยินยอม หรือหมายเลขโอนสาย {{variable}} call_setup_webhook_variables ของเอเจนต์จะแสดงรายการเหล่านี้

  • ต้องใช้เว็บฮุก: เมื่อเว็บฮุกหมดเวลา ติดต่อไม่ได้ หรือตอบกลับด้วยข้อผิดพลาดหรือเนื้อหาที่ไม่ใช่ออบเจ็กต์ JSON การโทรจะไม่เริ่ม แม้ว่าการโทรจะมีค่าสำหรับตัวแปรใดตัวแปรหนึ่งนั้นอยู่แล้ว ระบบจะยุติและบันทึกตามที่อธิบายไว้ในการหมดเวลาและการลองใหม่ (end_reason inbound_config_webhook_failed, ไม่มีการคิดค่าบริการ)
  • ไม่ต้องใช้ข้อมูลใด (ไม่มีตัวแปร หรือทุกตัวมีค่าเริ่มต้น เช่น {{first_name|there}}): เว็บฮุกจะยังทำงาน แต่เมื่อเว็บฮุกล้มเหลว เอเจนต์จะตอบรับสายโดยไม่มีข้อมูลจากเว็บฮุก และรายละเอียดการโทรจะแสดง webhook_failed พร้อม สาเหตุที่ล้มเหลว

บริบทการโทรเพียงอย่างเดียวจะไม่ทำให้ต้องใช้ webhook: ไม่มีสิ่งใดในการตั้งค่าของเอเจนต์ที่ระบุว่าต้องใช้บริบท ใช้ตัวแปรที่ไม่มีค่าเริ่มต้นหากการโทรต้องไม่เริ่มต้นโดยไม่มีคำตอบจาก webhook ของคุณ

การกำหนดและการปรับใช้ ไม่สามารถกำหนดเอเจนต์ที่ต้องใช้ webhook ให้กับหมายเลขที่ไม่มี webhook ได้: ระบบจะปฏิเสธการกำหนดพร้อมข้อความระบุชื่อตัวแปร การตรวจสอบเดียวกันจะทำงานเมื่อเวอร์ชันของหมายเลขเปลี่ยน รวมถึงเมื่อหมายเลขที่ปักหมุดย้ายกลับไปใช้เวอร์ชันล่าสุด ขณะที่เอเจนต์ตอบสายสำหรับหมายเลขด้วยการตั้งค่าที่เผยแพร่แล้ว การปรับใช้ที่เพิ่มตัวแปรดังกล่าวโดยไม่มี webhook (หรือลบ webhook) จะถูกปฏิเสธในลักษณะเดียวกัน อนุญาตให้บันทึกฉบับร่างได้เสมอ และ warnings ของเอเจนต์จะแสดง call_setup_webhook_needed จนกว่าจะแก้ไข

webhook ของเอเจนต์จะทำงานเฉพาะสำหรับสายโทรศัพท์ขาเข้าบนหมายเลขที่กำหนดให้เอเจนต์นั้นเท่านั้น สายขาออก เซสชันวิดเจ็ตเว็บ ที่อยู่ SIP การจำลอง และการสนทนาทดสอบในแดชบอร์ดจะไม่เรียกใช้ webhook นี้ แต่จะรับตัวแปรจากคำขอตามเดิม

การทดสอบด้วยตัวอย่างที่บันทึกไว้ หากต้องการทดสอบว่าเอเจนต์ของคุณทำงานอย่างไรกับคำตอบที่กำหนดไว้ (ผู้โทรที่โทรกลับ ไม่พบข้อมูล ผู้พูดภาษาสเปน) ให้บันทึกคำตอบนั้นไว้ในเอเจนต์เป็นตัวอย่าง ได้แก่ variables context และเลือกได้ว่าจะใส่ language โดยพิมพ์เองหรือคัดลอกจากการโทรที่ผ่านมา เลือกตัวอย่างเมื่อคุณเริ่มการสนทนาทดสอบในแดชบอร์ด การโทรทดสอบไปยังโทรศัพท์ของคุณ หรือการจำลองกับเอเจนต์ แล้วการโทรจะทำงานเสมือนว่าเว็บฮุกของคุณตอบกลับด้วยข้อมูลนั้น ตัวอย่างจะใช้ร่วมกันในทุกเวอร์ชันของเอเจนต์ การแก้ไขตัวอย่างหนึ่งรายการจะคงเวอร์ชันก่อนหน้าไว้: เมื่อการเปลี่ยนแปลงเอเจนต์ต้องใช้ตัวแปรที่ตัวอย่างไม่ได้ตั้งค่า ให้เพิ่มตัวแปรนั้นลงในตัวอย่าง และเอเจนต์เวอร์ชันเก่าจะยังคงใช้ตัวอย่างในสภาพเดิม การจำลองที่โทรไปยังหมายเลขโทรศัพท์จะเรียกใช้เว็บฮุกจริงของคุณแทน

หมายเลขที่ไม่ได้กำหนดเอเจนต์จะยังคงใช้ webhook ของหมายเลขหรือขององค์กรตามที่อธิบายข้างต้น


การโทรกลับ

ผู้คนมักโทรกลับไปยังหมายเลขที่เคยโทรหาพวกเขา เช่น หลังจาก เอเจนต์ของคุณฝากข้อความเสียงไว้ เมื่อมีสายโทรศัพท์เข้าจากบุคคลที่ หมายเลขเดียวกันเคยโทรหาในช่วง 30 วันที่ผ่านมา ThunderPhone จะค้นหาสายขาออกล่าสุดดังกล่าว (สายที่ทำให้โทรศัพท์ของบุคคลนั้นดัง) และใช้ข้อมูลดังกล่าวได้ 3 วิธีดังนี้:

  1. returning_call ในคำขอ คำขอแบบบล็อกด้านบน และการแจ้งเตือนเอนด์พอยต์ จะมีข้อมูลนี้ เพื่อให้ตัวจัดการของคุณกำหนดเส้นทางผู้โทรได้:

    {
      "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"
        }
      }
    }
    ฟิลด์ประเภทคำอธิบาย
    call_idจำนวนเต็มสายขาออกก่อนหน้า
    agent_idจำนวนเต็ม | nullเอเจนต์ที่โทรออก null สำหรับสายที่โทรโดยใช้การกำหนดค่าแบบอินไลน์ หรือสายที่เอเจนต์ถูกลบแล้ว
    started_atสตริงเวลาที่เริ่มต้น (ISO 8601, UTC)
    outcomeสตริงno_answer (สายดังจนหมดเวลา สายไม่ว่าง หรือถูกปฏิเสธ), voicemail (มีผู้รับข้อความเสียง หรือไม่มีใครพูดคุยกับเอเจนต์), conversation (มีผู้พูดคุยกับเอเจนต์) หรือ answered (มีผู้รับสายแล้ว แต่ยังไม่ทราบว่าใครรับสาย)
  2. ข้อมูลพื้นหลังสำหรับเอเจนต์ ไม่ว่าเอเจนต์ใดจะรับสาย จะได้รับ บันทึกย่อท้ายพรอมป์ต์ของเอเจนต์นั้น: เวลาที่โทรก่อนหน้า เอเจนต์ ที่โทรออก และผลลัพธ์ของสาย เอเจนต์จะได้รับคำสั่งไม่ให้อ่านข้อมูลนี้ ออกเสียง และเนื่องจากหมายเลขผู้โทรอาจถูกปลอมแปลง จึงห้ามเปิดเผยข้อมูล ใดเกี่ยวกับสายนั้นนอกเหนือจากการเคยโทรไปยังหมายเลขดังกล่าว

  3. เอเจนต์สำรอง เมื่อหมายเลขไม่มีเอเจนต์ขาเข้า และไม่มี การกำหนดค่ามาถึงเนื่องจากไม่มี URL ของเว็บฮุก หรือเว็บฮุกของคุณไม่ตอบกลับ (หมดเวลา ไม่สามารถเข้าถึงได้ หรือตอบกลับ 5xx, 408 หรือ 429 ในทั้งสองครั้ง) สายจะถูกส่งไปยังเอเจนต์ที่โทรออกในสายก่อนหน้าแทนที่จะสิ้นสุด ตราบใดที่เอเจนต์นั้นยังอยู่ในองค์กรของคุณ ระบบจะทำงานด้วยการตั้งค่าที่ปรับใช้ ของเอเจนต์นั้น คำตอบใดก็ตามที่เว็บฮุกของคุณส่งกลับยังคงเป็นตัวตัดสิน: 4xx อื่น เนื้อหาที่ไม่ใช่ออบเจ็กต์ JSON, {} หรือการกำหนดค่าที่ตรวจสอบไม่ผ่าน จะทำให้สายสิ้นสุดเช่นเดิม เอเจนต์ขาเข้าที่กำหนดไว้ในหมายเลขจะรับสายเสมอ

การแชร์รายละเอียดของสายก่อนหน้า หมายเลขผู้โทรอาจถูกปลอมแปลงได้ ดังนั้นโดย ค่าเริ่มต้น เนื้อหาใดจากสายก่อนหน้าจะไม่ส่งต่อไปยังสายใหม่ ผู้ดูแลองค์กรสามารถเปิด แชร์รายละเอียดของสายก่อนหน้า ได้ใน องค์กร → ทั่วไป → การโทรกลับ (หรือกำหนดค่า callback_context_details_enabled) เมื่อเปิดใช้งาน บันทึกของเอเจนต์จะอ้างอิงสรุปของสายก่อนหน้าด้วย และสายที่กำหนดเส้นทาง ไปยังเอเจนต์ที่โทรออกในสายก่อนหน้าจะทำงานพร้อม variables ของสายนั้น (เช่น ชื่อผู้ติดต่อ) เปิดใช้งานเฉพาะเมื่อรายละเอียดเหล่านั้นปลอดภัยที่จะแชร์กับทุกคน ที่โทรจากหมายเลขนั้น แม้เปิดใช้งานแล้ว สายที่อาจมีข้อมูลสุขภาพที่ได้รับการคุ้มครอง จะไม่ส่งสรุปหรือ variables ไปยังสายที่ไม่ได้กำหนดให้ประมวลผล PHI

ในรายละเอียดการโทร สายเรียกเข้าที่ตรงกับสายก่อนหน้าจะมีอ็อบเจ็กต์ callback ใน GET /v1/calls/{call_id}: ได้แก่ returning_call ข้างต้น routed_as_callback (ระบุว่า fallback รับสายหรือไม่) และ config_webhook_failure ({kind, attempts, http_status, host} เมื่อ webhook ของคุณไม่ตอบกลับและ fallback รับสาย มิฉะนั้นเป็น null) ดังนั้นการขัดข้องของ webhook ยังคงมองเห็นได้แม้ว่าจะมีการรับสายแล้ว


ขีดจำกัดขนาดการตอบกลับ


ตัวอย่างตัวจัดการ

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({});
  },
);

การตอบกลับพร้อมเครื่องมือฟังก์ชัน

แนบเครื่องมือเพื่อให้ AI สามารถเรียก API ของคุณระหว่างการสนทนาได้:

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

สรุปการตั้งค่า

ส่ง product: "bolt" แล้วปรับแต่งการโทรด้วยฟิลด์เหล่านี้ ค่า product รุ่นเก่า (spark และค่า storm-*) ยังคงใช้งานได้

ฟิลด์ค่าสิ่งที่แลกเปลี่ยน
intelligencecore, pro (ค่าเริ่มต้น)Core มีค่าใช้จ่ายต่ำกว่าและเริ่มตอบได้เร็วกว่า ส่วน Pro ทำตามพรอมต์ยาวได้อย่างน่าเชื่อถือมากกว่า
audio_tierlite, standard (ค่าเริ่มต้น), plus, maxระดับที่สูงขึ้นได้ยินได้ดีกว่าและมีค่าใช้จ่ายสูงกว่า Plus เพิ่มเวลา 1–2 วินาทีในบางเทิร์น ส่วนทุกคำตอบของ Max ใช้เวลา 3–4 วินาที (Max ยังไม่พร้อมให้ใช้งานทั่วไป)
endpointingfaster, fast, normal (ค่าเริ่มต้น), patientเวลารอที่สั้นลงจะตอบเร็วกว่าและมีค่าใช้จ่ายสูงกว่า
faster_repliestrue (ค่าเริ่มต้น), falseเพิ่มความเร็ว: ตอบเร็วขึ้นเล็กน้อย โดยมีค่าใช้จ่ายเพิ่มขึ้นเล็กน้อย

ที่เกี่ยวข้อง