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

การโทรแต่ละครั้งสามารถส่งข้อมูลเฉพาะการโทรได้ 2 ประเภท ใช้อย่างใดอย่างหนึ่งหรือใช้ทั้งสองอย่างร่วมกันได้:

- **`variables`**: ค่าที่มีชื่อเพื่อเติม `{{placeholders}}` ในพรอมต์ ใช้สำหรับฟิลด์ที่พรอมต์อ้างอิงตามชื่อ เช่น ชื่อผู้โทร หมายเลขบัญชี หรือช่วงเวลานัดหมาย
- **`context`**: ข้อความแบบอิสระที่เพิ่มหลังพรอมต์ ใช้สำหรับข้อมูลสรุปที่ไม่เหมาะกับเทมเพลต เช่น คำอธิบายงานสำหรับการโทรครั้งนี้ หรือบันทึกที่รวบรวมไว้ก่อนหน้านี้

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

```json
{
  "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`)

### ตัวแทนที่ใช้แทนค่าและค่าเริ่มต้น

```text
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 จะเพิ่มข้อมูลนี้ต่อท้าย
พรอมป์ต์ หลังจากเติมตัวแปรของพรอมป์ต์แล้ว โดยเป็นบล็อกที่มีตัวคั่นดังนี้:

```text
<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` ที่ไม่ถูกต้อง (ดูด้านล่าง)
- ช่องว่างต้นและท้ายจะถูกตัดออก และอักขระควบคุมและอักขระรูปแบบเดียวกับในค่าตัวแปรจะถูกลบออก
- บริบทเป็นส่วนหนึ่งของพรอมต์ของการโทร จึงนับรวมใน [ขนาดพรอมต์](/th/guides/pricing) ของการโทร

สำหรับเอเจนต์แบบ [ขั้นตอน](/th/guides/agent-steps) บริบทจะตามหลังพรอมป์ต์ของ
เอเจนต์ทุกตัวในการโทร ไม่ใช่ตามหลังคำสั่งของแต่ละขั้นตอน

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

### API ขาออก

ส่ง `variables` และ `context` ใน `POST /v1/call`:

```json
{
  "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 การโทรจะคงเสียงของเอเจนต์ไว้แม้การโทรจะเริ่มต้นด้วยภาษาอื่นที่รองรับ:
การแมปเสียงตามภาษาและการสลับเสียงเจ้าของภาษาจะไม่ถูกใช้กับการโทรนั้น

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "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`](/th/guides/dynamic-call-config) ต่อการโทร; ส่งการกำหนดค่าแบบอินไลน์เมื่อคุณต้องการ
แทนที่พรอมป์ต์หรือการตั้งค่าอื่น คำตอบ webhook จากเอเจนต์ที่บันทึกไว้
ใช้การแบ่ง A/B ที่ปรับใช้ของเอเจนต์กับทั้งการโทรศัพท์และการโทรผ่านวิดเจ็ต
ตัวแปรจะแสดงผลหลังจากเลือกตัวแปรเวอร์ชันแล้ว เมื่อคำตอบกำหนด `language` สำหรับ
เอเจนต์ที่ไม่ใช่ฟูลดูเพล็กซ์ การโทรจะใช้เสียงของภาษานั้นด้วย หาก
เอเจนต์ตั้งค่าเสียงสำหรับภาษานั้นไว้ คำตอบที่มี `prompt` จะใช้
การกำหนดค่าแบบอินไลน์เสมอ: `agent_id` ใดก็ตามในคำตอบนั้นจะถูกละเว้น รวมถึงข้อมูลเมตาที่เป็น null หรือ
ไม่ใช่จำนวนเต็ม พรอมป์ต์แบบอินไลน์ยังต้องผ่านการตรวจสอบความถูกต้องตามปกติ
คำตอบ webhook แบบอินไลน์สามารถมี `variables` และ `context` ได้เช่นกัน `context`
ที่ไม่ใช่สตริงหรือยาวเกินไปจะทำให้การแลกเปลี่ยนข้อมูลล้มเหลว: การโทรศัพท์จะ
ถูกปฏิเสธ และคำขอเซสชันวิดเจ็ตจะล้มเหลวด้วย `400` คำตอบ webhook จากเอเจนต์ที่บันทึกไว้
ใช้การแบ่ง A/B ที่ปรับใช้ของเอเจนต์กับทั้งการโทรศัพท์และการโทรผ่านวิดเจ็ต
ตัวแปรจะแสดงผลหลังจากเลือกตัวแปรเวอร์ชันแล้ว สำหรับการโทรศัพท์ขาเข้า ให้ใช้หมายเลขที่ไม่มีเอเจนต์ขาเข้า
กำหนดไว้ และกำหนดค่า webhook ของหมายเลขโทรศัพท์หรือขององค์กร; คีย์วิดเจ็ตใช้
`mode="webhook"` การแจ้งเตือนขาเข้าจากระบบปลายทางจะไม่มีคำตอบการกำหนดค่าแบบบล็อก

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

เพื่อให้หมายเลขยังคงกำหนดให้กับเอเจนต์ของหมายเลขนั้น และระบุเฉพาะค่าของการโทร ให้กำหนด[เว็บฮุกการตั้งค่าการโทร](/th/webhooks/call-incoming)ให้เอเจนต์

ก่อนที่เอเจนต์จะรับสายเรียกเข้าแต่ละครั้งบนหมายเลข เว็บฮุกจะได้รับข้อมูลการโทร รวมถึง id ชื่อ และเวอร์ชันของเอเจนต์ และตอบกลับด้วย `variables`, `context`, `language` และ `timezone` สำหรับการโทรเดียวกันตามข้างต้น โดยไม่ต้องมี `agent_id` เอเจนต์ที่การตั้งค่าใช้ตัวยึดตำแหน่งที่ไม่มีค่าเริ่มต้น ต้องใช้เว็บฮุกนี้เพื่อรับสายบนหมายเลขโทรศัพท์ การโทรจะไม่เริ่มต้นเมื่อเว็บฮุกล้มเหลว ตัวยึดตำแหน่งที่มีค่าเริ่มต้น เช่น `{{name|there}}` ช่วยให้เอเจนต์รับสายได้โดยไม่ต้องใช้เว็บฮุกนี้

### ส่วนหัว SIP

การโทรที่ไปถึงเอเจนต์ผ่าน SIP (เช่น [ที่อยู่ SIP](/th/guides/sip-addresses) หรือ
หมายเลขบนการเชื่อมต่อ SIP แบบกำหนดเอง) สามารถส่งบริบทในส่วนหัว `X-*` และ
`User-to-User` ได้ แต่ละรายการจะกลายเป็นตัวแปร `sip_` เช่น
`{{sip_x_amzn_connectcontactid}}` หรือ `{{sip_uui}}` โดยมีลำดับความสำคัญต่ำสุด:
ค่าชื่อเดียวกันจาก API หรือ webhook จะมีผลแทน ดู
[ส่งบริบทการโทรในส่วนหัว SIP](/th/guides/sip-addresses)
ค่าของส่วนหัวถูกกำหนดโดยผู้ส่ง ดังนั้นให้ถือว่าไม่น่าเชื่อถือ เช่นเดียวกับค่าที่
เบราว์เซอร์ส่งมา

### Widget session API

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

ฟิลด์ `context` ของเบราว์เซอร์ในวิดเจ็ตนั้นต่างออกไป: ฟิลด์นี้มีข้อความจาก
หน้าที่ผู้เข้าชมกำลังดูอยู่ ซึ่งเอเจนต์จะถือว่าเป็นเนื้อหาเว็บไซต์ (ดู
[ฝังวิดเจ็ตเว็บ](/th/guides/embed-web-widget)) บริบทต่อการโทรของการโทรผ่านวิดเจ็ต
มาจากเว็บฮุกการกำหนดค่าของคีย์โหมดเว็บฮุก ตามที่อธิบายข้างต้น เมื่อการโทร
มีทั้งสองอย่าง บริบทต่อการโทรจะมาก่อน แล้วจึงเป็นเนื้อหาหน้าเว็บ

### Realtime session API

`POST /v1/realtime/sessions` รับ `variables`, `context` และ `language` ระดับบนสุด
ร่วมกับ `agent_id` หรือ `config` แบบอินไลน์:

```json
{
  "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` แรก ซึ่งจะเริ่มเซสชันทันทีที่
ได้รับการอัปเดตนั้น:

```json
{
  "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` จะมีข้อมูลเหล่านี้ด้วย:

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

`prompt_snapshot` ของการโทร (`GET /v1/calls/{call_id}`) แสดงพรอมต์ของเอเจนต์
โดยมีการเติมตัวแปรและเพิ่มบล็อกบริบทแล้ว

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

การเล่นซ้ำของการโทรใน [ชุดการตรวจสอบ](/api-reference/validation-sets)
[การรันการเล่นซ้ำ](/api-reference/replay-runs) และ
[การตรวจสอบ](/api-reference/investigations) จะใช้ตัวแปรและบริบทของการโทรนั้น
ร่วมกับพรอมต์ที่กำลังทดสอบ ดังนั้นการเล่นซ้ำจึงทดสอบสิ่งที่เอเจนต์ในการโทรนั้นจะได้รับแจ้ง

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

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