Biến theo từng cuộc gọi

Cá nhân hóa tác nhân AI đã lưu cho từng cuộc gọi mà không thay đổi prompt, công cụ hoặc cài đặt đã triển khai của tác nhân đó.

Đặt các placeholder trong prompt của tác nhân đã lưu, rồi cung cấp một đối tượng variables khi bắt đầu cuộc gọi. Cấu hình đã lưu và lịch sử phiên bản vẫn không thay đổi. ThunderPhone kết xuất 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).

Placeholder và giá trị mặc định

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ị có thể là chuỗi, số, boolean hoặc null; boolean được kết xuất thành true và false. Các ký tự điều khiển Unicode (Cc) trừ dòng mới (\n), tab (\t), và ký tự xuống dòng (\r), tất cả ký tự định dạng (Cf) và điểm mã surrogate (Cs) đều bị xóa; \r\n được chuẩn hóa thành \n. Mỗi giá trị được giới hạn 2.000 ký tự khi kết xuất. 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 nằm trong 32 KB JSON UTF-8; đối tượng lớn hơn sẽ nhận 400 trong yêu cầu cuộc gọi/phiên, trong khi nhập chiến dịch báo cáo từng hàng không hợp lệ riêng lẻ. Mảng và đối tượng lồng nhau không được chấp nhận làm giá trị. Khóa metadata không khớp (ví dụ: tiêu đề CSV có khoảng trắng) được giữ lại và phản hồi lại nhưng không thể được tham chiếu bằng placeholder.

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

API gọi đi

Gửi variables cùng với agent_id trên 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"
  }
}

Cách này 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. Không thể dùng lại khóa idempotency với các biến khác nhau.

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ố hiện tự động sử dụng các biến này. Dùng các 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.

Webhook cấu hình động

Trên đường dẫn webhook cấu hình chặn, 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:

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

Các khóa trong phản hồi ghi đè biến ở cấp yêu cầu, trong khi các khóa yêu cầu khác được giữ nguyên. Giá trị phản hồi là null sẽ chọn giá trị mặc định của placeholder. Đối tượng đã hợp nhất cũng phải nằm trong giới hạn 32 KB. Phản hồi tác nhân AI đã lưu chỉ chấp nhận agent_id và variables; hãy trả về cấu hình nội tuyến khi bạn cần thay thế prompt hoặc cài đặt. 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, kể 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. Phản hồi webhook của tác nhân AI đã lưu sử dụng phân chia A/B đã triển khai của tác nhân AI cho cả cuộc gọi điện thoại và 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 AI đến được gán và cấu hình webhook của số điện thoại hoặc tổ chức đó; khóa widget sử dụng mode="webhook". Thông báo đến của hệ thống endpoint không cung cấp phản hồi cấu hình chặn.

POST /v1/widget/session chấp nhận một đối tượng variables cấp cao nhất. Khóa có thể xuất bản của nó 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 widget/realtime do trình duyệt cung cấp do phía client kiểm soát, được chuyển tiếp nguyên văn trong web.incoming sau bước xác thực và làm sạch chuỗi được mô tả ở trên, đồng thời được lặp lại vào webhook hoàn tất và lịch sử cuộc gọi. Không xem chúng là dữ liệu nhận dạng hoặc ủy quyền đáng tin cậy.

POST /v1/realtime/sessions chấp nhận variables cùng với agent_id (hoặc config nội tuyến). Đây là các trường API tạo phiên. Cầu nối Realtime WebSocket không chuyển tiếp tùy chọn variables; hãy cung cấp trực tiếp tùy chọn này cho API tạo phiên. Client widget phải bao gồm variables trong payload phiên được gửi; việc chuyển tiếp qua SDK không thuộc thay đổi API này. Các cuộc gọi kiểm thử mô phỏng và bằng mic trong Builder phân giải giá trị mặc định và placeholder bị thiếu nhưng không có đầu vào biến theo từng cuộc gọi.

Giá trị được trả về 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:

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

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

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

Việc kết xuất cũng áp dụng cho prompt tác nhân đã lưu hiện có và biến thể A/B, cấu hình outbound và realtime nội tuyến, cũng như prompt được trả về bởi webhook cấu hình. Các placeholder {{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. 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ê. Cuộc gọi mic trong Builder và cuộc gọi mô phỏng áp dụng cùng hành vi mặc định/để trống.