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

Developer cookbook

ตัวแปรและบริบทต่อการโทร

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

การโทรแต่ละครั้งสามารถส่งข้อมูลเฉพาะการโทรได้ 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 และการโทรจำลองใช้พฤติกรรมค่าเริ่มต้น/ข้อความว่างแบบเดียวกัน