Developer cookbook

ตัวแปรต่อการโทร

ปรับให้เอเจนต์ที่บันทึกไว้เหมาะกับการโทรแต่ละครั้ง โดยไม่เปลี่ยนพรอมต์ เครื่องมือ หรือการตั้งค่าที่ปรับใช้แล้ว

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

เมื่อไม่ต้องการค่า ให้ละเว้น variables อย่าส่ง null (ระบบจะปฏิเสธด้วย 400)

เพลซโฮลเดอร์และค่าเริ่มต้น#

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

ชื่อคำนึงถึงตัวพิมพ์เล็กและใหญ่ และเป็นไปตามรูปแบบ [A-Za-z_][A-Za-z0-9_]* อนุญาตให้มีช่องว่างรอบ ชื่อได้ โดยช่องว่างหลัง | ถือเป็นส่วนหนึ่งของค่าเริ่มต้นและจะ คงไว้ {{name|Friend}} จะใช้ Friend เมื่อไม่มี name หรือมีค่าเป็น null; สตริงว่างคือค่าที่ระบุมาอย่างชัดเจน ค่าที่ไม่มีและไม่มี ค่าเริ่มต้นจะกลายเป็นสตริงว่าง และชื่อของค่าเหล่านั้นจะแสดงใน unresolved_variables ข้อความระหว่างวงเล็บปีกกาคู่ที่ไม่ใช่เพลซโฮลเดอร์ที่ถูกต้องจะถูกลบ ข้อความในวงเล็บปีกกาคู่ ภายในค่าที่ระบุแต่ละค่าจะถูกลบแยกกัน โดยค่าหนึ่งไม่สามารถลบ ข้อความพรอมต์โดยรอบหรือค่าอื่นได้ ตัวคั่นวงเล็บปีกกาคู่ที่ไม่เข้าคู่กัน จะถูกลบเช่นกัน ตัวอย่าง JSON ในพรอมต์ต้องไม่ใช้ {{ ค่าเป็นข้อความธรรมดา ไม่เคยถูกประเมินผล เป็นโค้ดหรือขยายซ้ำเป็นเทมเพลต

ตัวแปรยังสามารถปรากฏในพรอมต์ตอบรับ ข้อความวอยซ์เมลขาออก และข้อความประกาศขอความยินยอมเมื่อมีการส่งฟิลด์นั้นสำหรับ การโทร เอเจนต์ไม่มีฟิลด์ first_message แยกต่างหาก: ให้ใส่ คำสั่งเปิดบทสนทนาไว้ในพรอมต์ เพลซโฮลเดอร์วอยซ์เมล {agent_name} และ {org_name} ที่มีอยู่ยังคงใช้งานได้

ค่าสามารถเป็นสตริง ตัวเลข บูลีน หรือ null; บูลีนจะแสดงผลเป็น true และ false อักขระควบคุม Unicode (Cc) ยกเว้นขึ้นบรรทัดใหม่ (\n) แท็บ (\t) และการคืนบรรทัด (\r) อักขระรูปแบบ (Cf) ทั้งหมด และโค้ดพอยต์ ตัวแทน (Cs) จะถูกลบ; \r\n จะถูกปรับให้เป็น \n แต่ละค่า มีความยาวได้ไม่เกิน 2,000 อักขระเมื่อแสดงผล สตริงที่ระบุจะถูกทำความสะอาดและ ตัดทอนก่อนจัดเก็บเช่นกัน ออบเจ็กต์ต้นฉบับต้องมีขนาดไม่เกิน 32 KB ของ JSON แบบ UTF-8; ออบเจ็กต์ที่ใหญ่กว่าจะได้รับ 400 สำหรับคำขอโทร/เซสชัน ขณะที่ การนำเข้าแคมเปญจะรายงานแต่ละแถวที่ไม่ถูกต้องแยกกัน ระบบไม่ ยอมรับอาร์เรย์และออบเจ็กต์ที่ซ้อนกันเป็นค่า คีย์เมทาดาทาที่ไม่ตรงรูปแบบ (เช่น ส่วนหัว CSV ที่มี ช่องว่าง) จะยังคงถูกเก็บและส่งกลับ แต่ไม่สามารถอ้างอิงด้วยเพลซโฮลเดอร์ได้

แหล่งที่มาของค่า#

API ขาออก#

ส่ง variables พร้อมกับ agent_id ใน POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

ใช้งานได้กับ AI เอเจนต์ขาออกเริ่มต้นของหมายเลขโทรศัพท์ หรือกับ config.prompt แบบอินไลน์ คีย์ idempotency ไม่สามารถนำมาใช้ซ้ำกับตัวแปรที่แตกต่างกันได้

CSV แคมเปญ#

คอลัมน์ CSV ที่ไม่ใช่หมายเลขโทรศัพท์จะถูกจัดเก็บเป็นตัวแปรผู้ติดต่ออยู่แล้ว การโทรออกแต่ละครั้ง จะใช้ตัวแปรเหล่านี้โดยอัตโนมัติ ใช้ส่วนหัว เช่น name, account_id และ appointment_slot ให้ตรงกับตัวยึดตำแหน่งของคุณ การแมปชื่อที่มีอยู่สามารถ รวมคอลัมน์ชื่อและนามสกุลเป็นตัวแปร name ได้

webhook การกำหนดค่าแบบไดนามิก#

บนเส้นทาง webhook การกำหนดค่าที่บล็อก ให้ส่งคืน AI เอเจนต์ที่บันทึกไว้ใน องค์กรของคุณ พร้อมค่าต่อการโทร:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

คีย์ในคำตอบจะเขียนทับตัวแปรระดับคำขอ ขณะที่คีย์อื่นในคำขอยังคงอยู่ ค่าคำตอบเป็น null จะเลือกค่าเริ่มต้นของตัวยึดตำแหน่ง ออบเจ็กต์ที่ผสานแล้วต้องมีขนาดไม่เกิน 32 KB เช่นกัน คำตอบของ AI เอเจนต์ที่บันทึกไว้รองรับเฉพาะ agent_id และ variables; ให้ส่งคืนการกำหนดค่าแบบอินไลน์เมื่อคุณต้องการ แทนที่พรอมต์หรือการตั้งค่า คำตอบที่มี prompt จะใช้การกำหนดค่าแบบอินไลน์เสมอ: agent_id ใดก็ตามในคำตอบนั้นจะถูกละเว้น รวมถึงข้อมูลเมตาที่เป็น null หรือไม่ใช่จำนวนเต็ม พรอมต์แบบอินไลน์ยังต้องผ่านการตรวจสอบตามปกติ คำตอบ webhook แบบอินไลน์สามารถมี variables ได้เช่นกัน คำตอบ webhook ของ AI เอเจนต์ที่บันทึกไว้ ใช้การแบ่ง A/B ที่ปรับใช้แล้วของเอเจนต์กับทั้งการโทรและวิดเจ็ต; ตัวแปรจะแสดงผลหลังจากเลือกตัวแปรย่อยแล้ว สำหรับสายโทรศัพท์ขาเข้า ให้ใช้หมายเลขที่ไม่มี AI เอเจนต์ขาเข้า ที่กำหนดไว้ และกำหนดค่า webhook ระดับหมายเลขโทรศัพท์หรือระดับองค์กร; คีย์วิดเจ็ตใช้ mode="webhook" การแจ้งเตือนขาเข้าจากระบบปลายทางจะไม่ส่งคำตอบ การกำหนดค่าแบบบล็อก

API เซสชัน Widget และ Realtime#

POST /v1/widget/session รองรับออบเจ็กต์ variables ระดับบนสุด คีย์ที่เผยแพร่ได้ของคีย์นี้ จะเลือก AI เอเจนต์ที่บันทึกไว้ คีย์โหมด webhook จะส่งต่อค่าเหล่านี้ไปยัง webhook การกำหนดค่า และผสานคำตอบตามที่อธิบายไว้ข้างต้น variables ของ widget/realtime ที่ส่งมาจากเบราว์เซอร์อยู่ภายใต้การควบคุมของไคลเอนต์ โดยจะถูกส่งต่อ ตามเดิมใน web.incoming หลังจากการตรวจสอบและการล้างสตริงตามที่อธิบายไว้ ข้างต้น และจะถูกส่งกลับใน completion webhook และประวัติการโทร อย่าถือว่าข้อมูลเหล่านี้ เป็นข้อมูลระบุตัวตนหรือข้อมูลการอนุญาตที่เชื่อถือได้

POST /v1/realtime/sessions รองรับ variables พร้อมกับ agent_id (หรือ config แบบอินไลน์) ฟิลด์เหล่านี้เป็นฟิลด์ของ API สร้างเซสชัน Realtime บริดจ์ Realtime WebSocket ไม่ส่งต่อตัวเลือก variables; ให้ระบุโดยตรงใน API สร้างเซสชัน ไคลเอนต์ Widget ต้องรวม variables ในเพย์โหลดเซสชันที่ส่ง ไป; การส่งต่อผ่าน SDK ไม่ได้เป็นส่วนหนึ่งของการเปลี่ยนแปลง API นี้ การทดสอบไมโครโฟนใน Builder และ การโทรทดสอบจำลองจะใช้ค่าเริ่มต้นและตัวยึดตำแหน่งที่ขาดหายไป แต่ไม่มีอินพุต ตัวแปรต่อการโทร

ค่าที่ส่งคืนหลังการโทร#

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete และ web.complete มี variables และ unresolved_variables สุดท้ายที่ผสานแล้ว เพย์โหลด completion แบบเดิม ที่มี data.history จะมีข้อมูลเหล่านี้ด้วย:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

จัดเก็บตัวระบุ CRM หรืองานของคุณไว้ในออบเจ็กต์ตัวแปร เพื่อเชื่อมโยงการโทรที่เสร็จสิ้นแล้ว กลับไปยังระเบียนต้นทาง ฟิลด์เหล่านี้จะถูกเก็บไว้กับระเบียนการโทร; ส่งเฉพาะข้อมูลที่เหมาะสมสำหรับการเก็บไว้ในประวัติการโทรและ webhook เท่านั้น

ความเข้ากันได้กับพรอมต์ที่มีอยู่#

การเรนเดอร์ยังใช้กับพรอมต์ของเอเจนต์ที่บันทึกไว้และตัวแปร A/B ที่มีอยู่ การกำหนดค่าแบบอินไลน์สำหรับการโทรออกและแบบเรียลไทม์ รวมถึงพรอมต์ที่ส่งกลับจากเว็บฮุกการกำหนดค่า ตัวยึดตำแหน่ง {{name}} ที่ไม่รู้จักจะกลายเป็นข้อความว่าง แม้ไม่ได้ระบุ variables ตรวจสอบพรอมต์ที่มีอยู่ก่อนเปิดใช้งาน รวมถึงพรอมต์แบบอินไลน์/เว็บฮุกที่มาจากภายนอกซึ่ง ThunderPhone ไม่สามารถจัดทำรายการได้ การโทรผ่านไมโครโฟนใน Builder และการโทรจำลองใช้พฤติกรรมค่าเริ่มต้น/ข้อความว่างแบบเดียวกัน