Open in
ตัวแปรและบริบทต่อการโทร
กำหนดรายละเอียดเฉพาะให้แต่ละการโทรในรูปแบบตัวแปรที่มีชื่อสำหรับพรอมต์หรือข้อมูลสรุปแบบอิสระ โดยไม่ต้องเปลี่ยนเอเจนต์
การโทรแต่ละครั้งสามารถส่งข้อมูลเฉพาะการโทรได้ 2 ประเภท ใช้อย่างใดอย่างหนึ่งหรือใช้ทั้งสองอย่างร่วมกันได้:
variables: ค่าที่มีชื่อเพื่อเติม{{placeholders}}ในพรอมต์ ใช้สำหรับฟิลด์ที่พรอมต์อ้างอิงตามชื่อ เช่น ชื่อผู้โทร หมายเลขบัญชี หรือช่วงเวลานัดหมายcontext: ข้อความแบบอิสระที่เพิ่มหลังพรอมต์ ใช้สำหรับข้อมูลสรุปที่ไม่เหมาะกับเทมเพลต เช่น คำอธิบายงานสำหรับการโทรครั้งนี้ หรือบันทึกที่รวบรวมไว้ก่อนหน้านี้
ทั้งสองแบบใช้ได้กับเอเจนต์ที่บันทึกไว้และการกำหนดค่าแบบอินไลน์ สำหรับทุกวิธีเริ่มการโทรที่อธิบายไว้ด้านล่าง และจะไม่เปลี่ยนแปลงเอเจนต์ที่บันทึกไว้ ประวัติเวอร์ชัน หรือการตั้งค่าอื่นๆ
{
"agent_id": 12,
"variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
"context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}ตัวแปร
ใส่ตัวยึดตำแหน่งในพรอมป์ต์ของเอเจนต์ที่บันทึกไว้ จากนั้นระบุอ็อบเจ็กต์ 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) ยกเว้นตัวไม่เชื่อมแบบความกว้างศูนย์และตัวเชื่อมแบบความกว้างศูนย์ (U+200C, U+200D ซึ่งใช้สะกดคำในภาษาอินดิกและภาษาที่ใช้อักษรอาหรับ) และจุดรหัสตัวแทน (Cs) จะถูกลบออก; \r\n
จะถูกปรับให้เป็น \n แต่ละค่า
จำกัดไว้ที่ 2,000 อักขระเมื่อแสดงผล สตริงที่ส่งมาจะถูกทำความสะอาดและ
ตัดทอนก่อนจัดเก็บด้วย ออบเจ็กต์ต้นฉบับต้องมีขนาดไม่เกิน 32 KB ของ JSON แบบ UTF-8; ออบเจ็กต์ที่ใหญ่กว่าจะได้รับ 400 ในคำขอการโทร/เซสชัน ขณะที่
การนำเข้าแคมเปญจะรายงานแต่ละแถวที่ไม่ถูกต้องแยกกัน ไม่รองรับอาร์เรย์และออบเจ็กต์ซ้อนเป็นค่า คีย์เมตาดาต้าที่ไม่ตรงกัน (เช่น ส่วนหัว CSV ที่มี
ช่องว่าง) จะถูกเก็บไว้และส่งกลับ แต่ไม่สามารถอ้างอิงด้วยตัวแทนที่ได้
บริบท
context คือสตริงที่มีความยาวได้สูงสุด 20,000 อักขระ ThunderPhone จะเพิ่มข้อมูลนี้ต่อท้าย
พรอมป์ต์ หลังจากเติมตัวแปรของพรอมป์ต์แล้ว โดยเป็นบล็อกที่มีตัวคั่นดังนี้:
<your prompt, with its variables filled in>
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>เอเจนต์จะอ่านข้อมูลนี้พร้อมกับคำสั่งของเอเจนต์ ดังนั้นให้เขียนในลักษณะเดียวกับที่คุณ
สรุปข้อมูลให้เพื่อนร่วมงานก่อนโทร บริบทไม่ใช่เทมเพลต:
{{name}} ภายในบริบทจะคงอยู่ตามที่เขียนไว้ หากข้อความต้องใช้ค่า ให้ใส่ค่านั้น
ด้วยตัวเองก่อนส่ง
nullสตริงว่าง หรือมีเพียงช่องว่าง หมายถึงไม่มีบริบท- ค่าที่ไม่ใช่สตริง หรือยาวเกิน 20,000 อักขระ จะถูกปฏิเสธด้วย
400ในคำขอการโทรและเซสชัน จาก webhook การกำหนดค่า การแลกเปลี่ยนจะล้มเหลวเช่นเดียวกับvariablesที่ไม่ถูกต้อง (ดูด้านล่าง) - ช่องว่างต้นและท้ายจะถูกตัดออก และอักขระควบคุมและอักขระรูปแบบเดียวกับในค่าตัวแปรจะถูกลบออก
- บริบทเป็นส่วนหนึ่งของพรอมต์ของการโทร จึงนับรวมใน ขนาดพรอมต์ ของการโทร
สำหรับเอเจนต์แบบ ขั้นตอน บริบทจะตามหลังพรอมป์ต์ของ เอเจนต์ทุกตัวในการโทร ไม่ใช่ตามหลังคำสั่งของแต่ละขั้นตอน
แหล่งที่มาของค่า
API ขาออก
ส่ง variables และ context ใน POST /v1/call:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"variables": {
"name": "Ada",
"account_id": "A-17",
"appointment_slot": "Tuesday at 10 AM"
},
"context": "Ada asked to be called back about the late fee on her March invoice."
}ทั้งสองรายการยังใช้ได้กับเอเจนต์เสียงขาออกเริ่มต้นของหมายเลขโทรศัพท์ หรือกับ config.prompt แบบอินไลน์ เมื่อใช้การกำหนดค่าแบบอินไลน์ คุณสามารถใส่ context ไว้ใน config ได้เช่นกัน ซึ่งเป็นฟิลด์เดียวกับที่ configuration webhook ส่งกลับมา หากส่งทั้งสองรายการ ข้อความต้องเหมือนกัน ไม่สามารถใช้ idempotency key ซ้ำกับตัวแปรหรือ context ที่แตกต่างกันได้
CSV แคมเปญ
คอลัมน์ CSV ที่ไม่ใช่หมายเลขโทรศัพท์จะถูกจัดเก็บเป็นตัวแปรรายชื่อติดต่ออยู่แล้ว การโทรออกแต่ละครั้งจะใช้ตัวแปรเหล่านี้โดยอัตโนมัติ ใช้ส่วนหัว เช่น name, account_id และ appointment_slot ให้ตรงกับตัวยึดตำแหน่งของคุณ การแมปชื่อที่มีอยู่สามารถรวมคอลัมน์ชื่อและนามสกุลเป็นตัวแปร name ได้ รายชื่อติดต่อในแคมเปญไม่มีบริบทเฉพาะรายชื่อติดต่อ
webhook การกำหนดค่าแบบไดนามิก
ในเส้นทาง webhook การกำหนดค่าแบบบล็อก ให้ส่งคืนเอเจนต์ที่บันทึกไว้ในองค์กรของคุณพร้อมค่าต่อการโทรใดๆ สำหรับเอเจนต์ Full duplex การโทรจะคงเสียงของเอเจนต์ไว้แม้การโทรจะเริ่มต้นด้วยภาษาอื่นที่รองรับ: การแมปเสียงตามภาษาและการสลับเสียงเจ้าของภาษาจะไม่ถูกใช้กับการโทรนั้น
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}ตัวแปรในคำตอบจะเขียนทับตัวแปรระดับคำขอ ขณะที่คีย์คำขออื่นยังคงอยู่ ค่า null ในคำตอบจะเลือกค่าเริ่มต้นของตัวยึดตำแหน่ง
ออบเจ็กต์ที่รวมแล้วต้องมีขนาดไม่เกิน 32 KB เช่นกัน คำตอบจากเอเจนต์ที่บันทึกไว้รับเฉพาะ
agent_id, variables, context, language และ
timezone ต่อการโทร; ส่งการกำหนดค่าแบบอินไลน์เมื่อคุณต้องการ
แทนที่พรอมป์ต์หรือการตั้งค่าอื่น คำตอบ webhook จากเอเจนต์ที่บันทึกไว้
ใช้การแบ่ง A/B ที่ปรับใช้ของเอเจนต์กับทั้งการโทรศัพท์และการโทรผ่านวิดเจ็ต
ตัวแปรจะแสดงผลหลังจากเลือกตัวแปรเวอร์ชันแล้ว เมื่อคำตอบกำหนด language สำหรับ
เอเจนต์ที่ไม่ใช่ฟูลดูเพล็กซ์ การโทรจะใช้เสียงของภาษานั้นด้วย หาก
เอเจนต์ตั้งค่าเสียงสำหรับภาษานั้นไว้ คำตอบที่มี prompt จะใช้
การกำหนดค่าแบบอินไลน์เสมอ: agent_id ใดก็ตามในคำตอบนั้นจะถูกละเว้น รวมถึงข้อมูลเมตาที่เป็น null หรือ
ไม่ใช่จำนวนเต็ม พรอมป์ต์แบบอินไลน์ยังต้องผ่านการตรวจสอบความถูกต้องตามปกติ
คำตอบ webhook แบบอินไลน์สามารถมี variables และ context ได้เช่นกัน context
ที่ไม่ใช่สตริงหรือยาวเกินไปจะทำให้การแลกเปลี่ยนข้อมูลล้มเหลว: การโทรศัพท์จะ
ถูกปฏิเสธ และคำขอเซสชันวิดเจ็ตจะล้มเหลวด้วย 400 คำตอบ webhook จากเอเจนต์ที่บันทึกไว้
ใช้การแบ่ง A/B ที่ปรับใช้ของเอเจนต์กับทั้งการโทรศัพท์และการโทรผ่านวิดเจ็ต
ตัวแปรจะแสดงผลหลังจากเลือกตัวแปรเวอร์ชันแล้ว สำหรับการโทรศัพท์ขาเข้า ให้ใช้หมายเลขที่ไม่มีเอเจนต์ขาเข้า
กำหนดไว้ และกำหนดค่า webhook ของหมายเลขโทรศัพท์หรือขององค์กร; คีย์วิดเจ็ตใช้
mode="webhook" การแจ้งเตือนขาเข้าจากระบบปลายทางจะไม่มีคำตอบการกำหนดค่าแบบบล็อก
เว็บฮุกการตั้งค่าการโทรของเอเจนต์
เพื่อให้หมายเลขยังคงกำหนดให้กับเอเจนต์ของหมายเลขนั้น และระบุเฉพาะค่าของการโทร ให้กำหนดเว็บฮุกการตั้งค่าการโทรให้เอเจนต์
ก่อนที่เอเจนต์จะรับสายเรียกเข้าแต่ละครั้งบนหมายเลข เว็บฮุกจะได้รับข้อมูลการโทร รวมถึง id ชื่อ และเวอร์ชันของเอเจนต์ และตอบกลับด้วย variables, context, language และ timezone สำหรับการโทรเดียวกันตามข้างต้น โดยไม่ต้องมี agent_id เอเจนต์ที่การตั้งค่าใช้ตัวยึดตำแหน่งที่ไม่มีค่าเริ่มต้น ต้องใช้เว็บฮุกนี้เพื่อรับสายบนหมายเลขโทรศัพท์ การโทรจะไม่เริ่มต้นเมื่อเว็บฮุกล้มเหลว ตัวยึดตำแหน่งที่มีค่าเริ่มต้น เช่น {{name|there}} ช่วยให้เอเจนต์รับสายได้โดยไม่ต้องใช้เว็บฮุกนี้
ส่วนหัว SIP
การโทรที่ไปถึงเอเจนต์ผ่าน SIP (เช่น ที่อยู่ SIP หรือ
หมายเลขบนการเชื่อมต่อ SIP แบบกำหนดเอง) สามารถส่งบริบทในส่วนหัว X-* และ
User-to-User ได้ แต่ละรายการจะกลายเป็นตัวแปร sip_ เช่น
{{sip_x_amzn_connectcontactid}} หรือ {{sip_uui}} โดยมีลำดับความสำคัญต่ำสุด:
ค่าชื่อเดียวกันจาก API หรือ webhook จะมีผลแทน ดู
ส่งบริบทการโทรในส่วนหัว SIP
ค่าของส่วนหัวถูกกำหนดโดยผู้ส่ง ดังนั้นให้ถือว่าไม่น่าเชื่อถือ เช่นเดียวกับค่าที่
เบราว์เซอร์ส่งมา
Widget session API
POST /v1/widget/session รับ variables และ language ระดับบนสุด คีย์ที่เผยแพร่ได้ของคีย์นี้จะเลือกเอเจนต์ที่บันทึกไว้ คีย์โหมด Webhook จะส่งต่อค่าเหล่านี้ไปยัง Webhook การกำหนดค่าและรวมการตอบกลับตามที่อธิบายไว้ข้างต้น
variables ของวิดเจ็ตที่เบราว์เซอร์ส่งมาจะถูกควบคุมโดยไคลเอนต์ ส่งต่อแบบเดิมใน web.incoming หลังการตรวจสอบและการล้างสตริงตามที่อธิบายไว้ข้างต้น และส่งกลับไปยัง Webhook เมื่อเสร็จสิ้นและประวัติการโทร ห้ามถือว่าข้อมูลเหล่านี้เป็นข้อมูลระบุตัวตนหรือข้อมูลการอนุญาตที่เชื่อถือได้
ฟิลด์ context ของเบราว์เซอร์ในวิดเจ็ตนั้นต่างออกไป: ฟิลด์นี้มีข้อความจาก
หน้าที่ผู้เข้าชมกำลังดูอยู่ ซึ่งเอเจนต์จะถือว่าเป็นเนื้อหาเว็บไซต์ (ดู
ฝังวิดเจ็ตเว็บ) บริบทต่อการโทรของการโทรผ่านวิดเจ็ต
มาจากเว็บฮุกการกำหนดค่าของคีย์โหมดเว็บฮุก ตามที่อธิบายข้างต้น เมื่อการโทร
มีทั้งสองอย่าง บริบทต่อการโทรจะมาก่อน แล้วจึงเป็นเนื้อหาหน้าเว็บ
Realtime session API
POST /v1/realtime/sessions รับ variables, context และ language ระดับบนสุด
ร่วมกับ agent_id หรือ config แบบอินไลน์:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context ต้องอยู่ในระดับบนสุดเท่านั้น; config แบบอินไลน์จะปฏิเสธฟิลด์นี้เนื่องจากเป็น
ฟิลด์ที่ไม่รู้จัก
Realtime WebSocket
เมื่อใช้เอเจนต์ที่บันทึกไว้ พรอมต์ที่ปรับใช้แล้วของเอเจนต์นั้นจะยังคงเป็นพรอมต์ของเอเจนต์
session.instructions จะกลายเป็นบริบทของการโทร session.prompt.variables
(หรือ session.config.variables) จะกลายเป็นตัวแปร และ session.language
จะกลายเป็นภาษาสำหรับการโทรนั้น เลือกเอเจนต์ด้วย
session.prompt.id ใน session.update แรก ซึ่งจะเริ่มเซสชันทันทีที่
ได้รับการอัปเดตนั้น:
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {"id": "12", "variables": {"name": "Ada"}},
"instructions": "Ada asked for a callback about her delivery window."
}
}?agent_id=12 ใน URL การเชื่อมต่อจะเริ่มเอเจนต์ทันทีที่ซ็อกเก็ต
เชื่อมต่อ ก่อนมี session.update ใดๆ ดังนั้นจึงไม่มีข้อมูลเฉพาะการโทร เพิ่ม
&wait_for_session_update=1 เพื่อรอ session.update รายการแรกและใช้
คำสั่งและตัวแปรของรายการนั้น
ในเซสชันแบบอินไลน์ (ไม่มีเอเจนต์ที่บันทึกไว้) session.instructions คือพรอมป์ต์
โดยตรงเช่นเดิม การโทรทดสอบไมโครโฟนใน 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"]
}prompt_snapshot ของการโทร (GET /v1/calls/{call_id}) แสดงพรอมต์ของเอเจนต์
โดยมีการเติมตัวแปรและเพิ่มบล็อกบริบทแล้ว
จัดเก็บตัวระบุ CRM หรือภารกิจของคุณไว้ในออบเจ็กต์ตัวแปร เพื่อเชื่อมโยงการโทรที่เสร็จสิ้นแล้ว กลับไปยังระเบียนต้นทาง ตัวแปรและบริบทจะถูกเก็บไว้พร้อมกับระเบียนการโทร ควรส่งเฉพาะข้อมูลที่เหมาะสม สำหรับการเก็บไว้ในประวัติการโทรและเว็บฮุก
การเล่นซ้ำของการโทรใน ชุดการตรวจสอบ การรันการเล่นซ้ำ และ การตรวจสอบ จะใช้ตัวแปรและบริบทของการโทรนั้น ร่วมกับพรอมต์ที่กำลังทดสอบ ดังนั้นการเล่นซ้ำจึงทดสอบสิ่งที่เอเจนต์ในการโทรนั้นจะได้รับแจ้ง
ความเข้ากันได้กับพรอมต์ที่มีอยู่
การเรนเดอร์ยังใช้กับพรอมต์ของเอเจนต์ที่บันทึกไว้และตัวแปร A/B ที่มีอยู่ การกำหนดค่าแบบอินไลน์สำหรับการโทรออกและแบบเรียลไทม์ รวมถึงพรอมต์ที่ส่งกลับจากเว็บฮุกการกำหนดค่า ตัวยึดตำแหน่ง {{name}} ที่ไม่รู้จักจะกลายเป็นข้อความว่าง แม้ไม่ได้ระบุ variables ตรวจสอบพรอมต์ที่มีอยู่ก่อนเปิดใช้งาน รวมถึงพรอมต์แบบอินไลน์/เว็บฮุกที่มาจากภายนอกซึ่ง ThunderPhone ไม่สามารถจัดทำรายการได้ การโทรผ่านไมโครโฟนใน Builder และการโทรจำลองใช้พฤติกรรมค่าเริ่มต้น/ข้อความว่างแบบเดียวกัน