---
title: "Biến và ngữ cảnh theo từng cuộc gọi"
description: "Cung cấp cho mỗi cuộc gọi thông tin riêng, dưới dạng biến có tên cho prompt hoặc bản tóm tắt tự do, mà không cần thay đổi tác nhân AI."
---

Mỗi cuộc gọi có thể mang hai loại dữ liệu đầu vào riêng cho cuộc gọi. Dùng một loại hoặc dùng cả hai
cùng nhau:

- **`variables`**: các giá trị được đặt tên để điền vào `{{placeholders}}` trong prompt. Dùng
  cho các trường mà prompt tham chiếu theo tên, chẳng hạn như tên người gọi, số tài khoản hoặc khung giờ hẹn.
- **`context`**: văn bản tự do được thêm sau prompt. Dùng cho bản tóm tắt không phù hợp với mẫu, chẳng hạn như mô tả tác vụ cho cuộc gọi này hoặc ghi chú đã thu thập trước đó.

Cả hai đều hoạt động với tác nhân AI đã lưu và cấu hình nội tuyến, trên mọi cách bắt đầu cuộc gọi được mô tả bên dưới. Không loại nào thay đổi tác nhân AI đã lưu, lịch sử phiên bản hoặc các cài đặt khác của tác nhân AI.

```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."
}
```

## Biến

Đặt các phần giữ chỗ trong prompt của tác nhân AI đã lưu, rồi cung cấp một đối tượng `variables`
khi bắt đầu cuộc gọi. ThunderPhone hiển thị văn bản trước khi gửi cấu hình
cuộc gọi đến thời gian chạy giọng nói.

Khi không cần giá trị, hãy bỏ qua `variables`, không gửi `null` (bị từ chối với `400`).

### Trình giữ chỗ và giá trị mặc định

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

Tên phân biệt chữ hoa chữ thường và tuân theo `[A-Za-z_][A-Za-z0-9_]*`. Khoảng trắng xung quanh
tên được cho phép; khoảng trắng sau `|` là một phần của giá trị mặc định và được
giữ nguyên. `{{name|Friend}}` sử dụng `Friend` khi thiếu `name` hoặc giá trị là
`null`; chuỗi rỗng là giá trị được cung cấp rõ ràng. Giá trị thiếu mà không có
giá trị mặc định sẽ trở thành chuỗi rỗng và tên của chúng xuất hiện trong `unresolved_variables`.
Văn bản giữa dấu ngoặc kép không phải placeholder hợp lệ sẽ bị xóa. Văn bản trong dấu ngoặc kép
bên trong từng giá trị được cung cấp sẽ bị xóa độc lập; một giá trị không thể xóa
văn bản prompt xung quanh hoặc giá trị khác. Dấu phân cách ngoặc kép không khớp cũng
bị xóa. Ví dụ JSON trong prompt không được dùng `{{`.
Giá trị là văn bản thuần túy, không bao giờ được đánh giá
dưới dạng mã hoặc mở rộng đệ quy dưới dạng mẫu.

Biến cũng có thể xuất hiện trong prompt xác nhận, tin nhắn thư thoại
gọi đi và văn bản thông báo đồng ý khi trường đó được gửi cho một
cuộc gọi điện thoại. Tác nhân AI không có trường `first_message` riêng: hãy đặt
hướng dẫn mở đầu trong prompt. Các placeholder thư thoại hiện có `{agent_name}` và `{org_name}`
tiếp tục hoạt động.

### Giá trị và giới hạn

Giá trị có thể là chuỗi, số, boolean hoặc `null`; boolean được hiển thị là `true`
và `false`. Các ký tự điều khiển Unicode (`Cc`) ngoại trừ dòng mới (`\n`), tab (`\t`),
và ký tự xuống dòng kiểu carriage return (`\r`), các ký tự định dạng (`Cf`) ngoại trừ ký tự không nối và nối có độ rộng bằng không (U+200C, U+200D, được dùng để ghép từ trong các ngôn ngữ dùng chữ Indic và chữ Ả Rập), cùng các điểm mã surrogate (`Cs`) sẽ bị xóa; `\r\n`
được chuẩn hóa thành `\n`. Mỗi giá trị
bị giới hạn ở 2.000 ký tự khi được hiển thị. Chuỗi được cung cấp cũng được làm sạch và
cắt ngắn trước khi lưu trữ. Đối tượng gốc phải vừa trong **32 KB JSON UTF-8**; các
đối tượng lớn hơn nhận `400` trên yêu cầu cuộc gọi/phiên, trong khi
quá trình nhập chiến dịch báo cáo riêng từng hàng không hợp lệ. Mảng và đối tượng lồng nhau không được
chấp nhận làm giá trị. Các khóa metadata không khớp (ví dụ: tiêu đề CSV có khoảng
trắng) vẫn được giữ lại và phản hồi nhưng không thể được tham chiếu bằng placeholder.

## Ngữ cảnh

`context` là một chuỗi có tối đa **20.000 ký tự**. ThunderPhone thêm chuỗi này sau
prompt, sau khi các biến của prompt đã được điền, dưới dạng một khối được phân cách:

```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>
```

Tác nhân AI đọc nội dung này cùng với hướng dẫn của nó, vì vậy hãy viết theo cách
bạn sẽ tóm tắt cho một đồng nghiệp trước cuộc gọi. Ngữ cảnh không phải là template:
`{{name}}` bên trong vẫn giữ nguyên như đã viết. Nếu văn bản cần một giá trị, hãy tự
điền giá trị đó trước khi gửi.

- `null`, chuỗi rỗng hoặc chỉ có khoảng trắng nghĩa là không có ngữ cảnh.
- Giá trị không phải là chuỗi hoặc dài hơn 20.000 ký tự sẽ bị từ chối với mã `400` trong yêu cầu cuộc gọi và phiên; từ webhook cấu hình, việc trao đổi sẽ thất bại như `variables` không hợp lệ (xem bên dưới).
- Khoảng trắng ở đầu và cuối được cắt bỏ, đồng thời các ký tự điều khiển và định dạng giống như trong giá trị biến cũng được loại bỏ.
- Ngữ cảnh là một phần của prompt của cuộc gọi, vì vậy nó được tính vào [kích thước prompt](/vi/guides/pricing) của cuộc gọi.

Trên tác nhân AI [có các bước](/vi/guides/agent-steps), ngữ cảnh theo sau prompt của
mọi tác nhân AI trong cuộc gọi, không phải hướng dẫn của từng bước.

## Nguồn gốc của giá trị

### API gọi đi

Gửi `variables` và `context` qua `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."
}
```

Cả hai cũng hoạt động với tác nhân AI gọi đi mặc định của số điện thoại hoặc với `config.prompt` nội tuyến. Với cấu hình nội tuyến, `context` cũng có thể nằm trong `config`, cùng trường mà webhook cấu hình trả về; nếu bạn gửi cả hai, chúng phải có cùng nội dung văn bản. Không thể sử dụng lại khóa idempotency với các biến khác hoặc một context khác.

### CSV chiến dịch

Các cột CSV không phải số điện thoại đã được lưu dưới dạng biến liên hệ. Mỗi lần quay số giờ đây tự động sử dụng các biến này. Dùng tiêu đề như `name`, `account_id` và `appointment_slot` để khớp với các placeholder của bạn. Ánh xạ tên hiện có có thể kết hợp cột tên và họ thành biến `name`. Liên hệ trong chiến dịch không có ngữ cảnh riêng cho từng liên hệ.

### Webhook cấu hình động

Trên đường dẫn webhook cấu hình chặn, hãy trả về một tác nhân AI đã lưu trong tổ chức của bạn cùng với mọi giá trị theo từng cuộc gọi. Đối với tác nhân Full duplex, cuộc gọi giữ nguyên giọng nói của tác nhân ngay cả khi cuộc gọi bắt đầu bằng một ngôn ngữ được hỗ trợ khác: các ánh xạ giọng nói theo ngôn ngữ và tính năng chuyển đổi giọng nói bản địa không áp dụng cho cuộc gọi đó.

```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."
}
```

Các biến trong phản hồi sẽ ghi đè các biến ở cấp yêu cầu, trong khi các khóa yêu cầu khác vẫn giữ nguyên. Giá trị phản hồi là `null` sẽ chọn giá trị mặc định của chỗ giữ chỗ.
Đối tượng đã hợp nhất cũng phải nằm trong giới hạn 32 KB. Phản hồi của tác nhân đã lưu chỉ chấp nhận
`agent_id`, `variables`, `context`, `language` và một
[`timezone`](/vi/guides/dynamic-call-config) cho mỗi cuộc gọi; hãy trả về cấu hình nội tuyến khi bạn cần
thay thế prompt hoặc các cài đặt khác. Phản hồi webhook của tác nhân đã lưu
sử dụng phân chia A/B đã triển khai của tác nhân cho cả cuộc gọi điện thoại và cuộc gọi qua widget;
các biến được hiển thị sau khi chọn biến thể. Khi phản hồi đặt `language` cho một
tác nhân không phải Full duplex, cuộc gọi cũng sử dụng giọng nói riêng của ngôn ngữ đó nếu
tác nhân đã đặt giọng nói cho ngôn ngữ này. Phản hồi chứa `prompt` luôn sử dụng cấu hình nội tuyến:
mọi `agent_id` trong phản hồi đó đều bị bỏ qua, bao gồm cả siêu dữ liệu null hoặc
không phải số nguyên. Prompt nội tuyến vẫn phải vượt qua quy trình xác thực thông thường.
Phản hồi webhook nội tuyến cũng có thể bao gồm `variables` và `context`. Một `context`
không phải chuỗi hoặc quá dài sẽ khiến quá trình trao đổi thất bại: cuộc gọi điện thoại
bị từ chối và yêu cầu phiên widget thất bại với `400`. Phản hồi webhook của tác nhân đã lưu
sử dụng phân chia A/B đã triển khai của tác nhân cho cả cuộc gọi điện thoại và cuộc gọi qua widget;
các biến được hiển thị sau khi chọn biến thể. Với cuộc gọi điện thoại đến, hãy dùng một số không có tác nhân xử lý cuộc gọi đến
được gán và cấu hình webhook ở cấp số điện thoại hoặc tổ chức; khóa widget sử dụng
`mode="webhook"`. Thông báo đến từ hệ thống endpoint không cung cấp phản hồi cấu hình chặn.

### Webhook thiết lập cuộc gọi của tác nhân

Để giữ một số điện thoại được gán cho tác nhân AI của số đó và chỉ điền các giá trị của cuộc gọi, hãy cung cấp cho tác nhân AI một [webhook thiết lập cuộc gọi](/vi/webhooks/call-incoming).
Trước mỗi cuộc gọi đến mà tác nhân AI trả lời trên một số điện thoại, webhook nhận cuộc gọi cùng id, tên và phiên bản của tác nhân AI, rồi phản hồi bằng các giá trị `variables`, `context`, `language` và `timezone` theo từng cuộc gọi giống như ở trên mà không cần `agent_id`. Một tác nhân AI có cài đặt sử dụng placeholder không có giá trị mặc định cần webhook này để trả lời số điện thoại: cuộc gọi sẽ không bắt đầu khi webhook gặp lỗi. Các placeholder có giá trị mặc định, như `{{name|there}}`, cho phép tác nhân AI trả lời mà không cần webhook này.

### Tiêu đề SIP

Các cuộc gọi đến một tác nhân AI qua SIP (một [địa chỉ SIP](/vi/guides/sip-addresses), hoặc
một số trên kết nối SIP thủ công) có thể mang ngữ cảnh trong các tiêu đề `X-*` và
`User-to-User`. Mỗi tiêu đề trở thành một biến `sip_`, chẳng hạn như
`{{sip_x_amzn_connectcontactid}}` hoặc `{{sip_uui}}`, với mức ưu tiên thấp nhất:
giá trị cùng tên từ API hoặc webhook sẽ được ưu tiên. Xem
[Truyền ngữ cảnh cuộc gọi trong tiêu đề SIP](/vi/guides/sip-addresses).
Giá trị tiêu đề do người gửi thiết lập, vì vậy hãy coi chúng là không đáng tin cậy,
tương tự như mọi giá trị do trình duyệt cung cấp.

### API phiên widget

`POST /v1/widget/session` chấp nhận `variables` và `language` ở cấp cao nhất. Khóa có thể công khai của khóa này sẽ chọn tác nhân AI đã lưu. Khóa ở chế độ webhook chuyển tiếp các giá trị này đến webhook cấu hình và hợp nhất phản hồi như mô tả ở trên.
`variables` của widget do trình duyệt cung cấp do phía máy khách kiểm soát, được chuyển tiếp nguyên văn trong `web.incoming` sau khi xác thực và làm sạch chuỗi như mô tả ở trên, đồng thời được phản chiếu vào webhook hoàn tất và lịch sử cuộc gọi. Không xem chúng là dữ liệu danh tính hoặc dữ liệu ủy quyền đáng tin cậy.

Trường `context` của trình duyệt riêng widget thì khác: trường này mang văn bản từ
trang mà khách truy cập đang xem, và tác nhân AI coi đó là nội dung website (xem
[Nhúng widget web](/vi/guides/embed-web-widget)). Ngữ cảnh theo từng cuộc gọi của một cuộc gọi widget
đến từ webhook cấu hình của khóa ở chế độ webhook, như trên. Khi một
cuộc gọi có cả hai, ngữ cảnh theo từng cuộc gọi xuất hiện trước, sau đó là nội dung trang.

### API phiên thời gian thực

`POST /v1/realtime/sessions` chấp nhận `variables`, `context` và `language` ở cấp cao nhất
cùng với `agent_id` hoặc `config` nội tuyến:

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}
```

`context` chỉ được đặt ở cấp cao nhất; `config` nội tuyến sẽ từ chối nó như một
trường không xác định.

### WebSocket thời gian thực

Với tác nhân AI đã lưu, prompt đã triển khai của tác nhân AI đó vẫn là prompt của nó.
`session.instructions` trở thành ngữ cảnh của cuộc gọi, `session.prompt.variables`
(hoặc `session.config.variables`) trở thành các biến của nó, và `session.language`
trở thành ngôn ngữ riêng cho từng cuộc gọi. Chọn tác nhân AI bằng
`session.prompt.id` trong `session.update` đầu tiên; phiên sẽ bắt đầu khi
bản cập nhật đó đến:

```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` trên URL kết nối khởi động tác nhân AI ngay khi socket
kết nối, trước mọi `session.update`, vì vậy nó không mang dữ liệu đầu vào theo từng cuộc gọi. Thêm
`&wait_for_session_update=1` để chờ `session.update` đầu tiên và sử dụng
hướng dẫn cùng biến của nó.

Trong phiên nội tuyến (không có tác nhân đã lưu), `session.instructions` là chính prompt, như trước đây. Cuộc gọi kiểm thử trên trình duyệt và mô phỏng sẽ phân giải các giá trị mặc định và chỗ giữ chỗ bị thiếu. Để kiểm thử với các giá trị, hãy lưu một
[mẫu thiết lập cuộc gọi](/vi/webhooks/call-incoming) trên tác nhân và chọn mẫu đó khi bạn bắt đầu kiểm thử; cuộc gọi sẽ chạy như thể webhook thiết lập cuộc gọi của bạn đã phản hồi bằng mẫu đó.

## Sau cuộc gọi

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` và `web.complete` bao gồm
`variables` và `unresolved_variables` cuối cùng đã được hợp nhất. Payload hoàn tất cũ
có bao gồm `data.history` cũng bao gồm chúng:

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

`prompt_snapshot` của cuộc gọi (`GET /v1/calls/{call_id}`) hiển thị prompt của tác nhân AI
với các biến đã được điền và khối ngữ cảnh đã được thêm vào.

Lưu mã định danh CRM hoặc tác vụ của bạn trong đối tượng biến để liên kết cuộc gọi đã hoàn tất
với bản ghi nguồn. Biến và ngữ cảnh được lưu giữ cùng bản ghi cuộc gọi; chỉ gửi thông tin phù hợp
để lưu trong lịch sử cuộc gọi và webhook.

Bản phát lại của một cuộc gọi trong [tập xác thực](/api-reference/validation-sets),
[lần chạy phát lại](/api-reference/replay-runs) và
[điều tra](/api-reference/investigations) sử dụng biến và ngữ cảnh của cuộc gọi đó
với prompt đang được kiểm thử, vì vậy một bản phát lại sẽ kiểm tra những gì tác nhân AI
trong cuộc gọi đó đã được cung cấp.

## Khả năng tương thích với prompt hiện có

Quá trình hiển thị cũng áp dụng cho các prompt tác nhân đã lưu và biến thể A/B hiện có, cấu hình outbound và realtime nội tuyến, cũng như các prompt được trả về bởi webhook cấu hình. Các phần giữ chỗ `{{name}}` không xác định sẽ trở thành văn bản trống, ngay cả khi không cung cấp `variables`. Hãy kiểm tra các prompt hiện có trước khi triển khai, bao gồm prompt nội tuyến/webhook được cung cấp từ bên ngoài mà ThunderPhone không thể kiểm kê. Các cuộc gọi thử nghiệm và mô phỏng trên trình duyệt áp dụng cùng hành vi mặc định/trống, trừ khi bạn chọn một mẫu thiết lập cuộc gọi đã lưu.
