Variabel per panggilan

Personalisasikan agen yang disimpan untuk setiap panggilan tanpa mengubah Prompt, alat, atau pengaturan yang telah di-deploy.

Masukkan placeholder ke dalam Prompt agen tersimpan Anda, lalu berikan objek variables saat memulai panggilan. Konfigurasi tersimpan dan riwayat versi tetap tidak berubah. ThunderPhone merender teks sebelum mengirim konfigurasi panggilan ke runtime suara.

Saat tidak ada nilai yang diperlukan, hilangkan variables, jangan kirim null (ditolak dengan 400).

Placeholder dan nilai default

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

Nama peka huruf besar-kecil dan mengikuti [A-Za-z_][A-Za-z0-9_]*. Spasi di sekitar nama diperbolehkan; spasi setelah | merupakan bagian dari nilai default dan dipertahankan. {{name|Friend}} menggunakan Friend ketika name tidak ada atau null; string kosong adalah nilai yang diberikan secara eksplisit. Nilai yang tidak ada tanpa default menjadi string kosong dan namanya muncul di unresolved_variables. Teks di antara kurung kurawal ganda yang bukan placeholder valid akan dihapus. Teks berkurung kurawal ganda di dalam setiap nilai yang diberikan dihapus secara terpisah; sebuah nilai tidak dapat menghapus teks Prompt di sekitarnya atau nilai lain. Pembatas kurung kurawal ganda yang tidak berpasangan juga dihapus. Contoh JSON dalam Prompt tidak boleh menggunakan {{. Nilai adalah teks biasa, tidak pernah dievaluasi sebagai kode atau diperluas secara rekursif sebagai template.

Variabel juga dapat muncul dalam Prompt konfirmasi, pesan voicemail keluar, dan teks pengumuman persetujuan saat kolom tersebut dikirim untuk panggilan telepon. Agen tidak memiliki kolom first_message terpisah: masukkan instruksi pembukanya ke dalam Prompt. Placeholder voicemail {agent_name} dan {org_name} yang ada tetap berfungsi.

Nilai dapat berupa string, angka, boolean, atau null; boolean dirender sebagai true dan false. Karakter kontrol Unicode (Cc) selain baris baru (\n), tab (\t), dan carriage return (\r), semua karakter format (Cf), serta titik kode surrogate (Cs) dihapus; \r\n dinormalisasi menjadi \n. Setiap nilai dibatasi hingga 2.000 karakter saat dirender. String yang diberikan juga dibersihkan dan dipotong sebelum disimpan. Objek asli harus muat dalam 32 KB JSON UTF-8; objek yang lebih besar menerima 400 pada permintaan panggilan/sesi, sedangkan impor kampanye melaporkan baris yang tidak valid secara terpisah. Array dan objek bertingkat tidak diterima sebagai nilai. Kunci metadata yang tidak cocok (misalnya header CSV dengan spasi) dipertahankan dan dikembalikan tetapi tidak dapat dirujuk oleh placeholder.

Asal nilai

API outbound

Kirim variables bersama agent_id pada 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"
  }
}

Ini juga berfungsi dengan agen outbound default nomor telepon, atau dengan config.prompt inline. Kunci idempotensi tidak dapat digunakan kembali dengan variabel yang berbeda.

CSV kampanye

Kolom CSV non-telepon sudah disimpan sebagai variabel kontak. Setiap panggilan kini menggunakannya secara otomatis. Gunakan header seperti name, account_id, dan appointment_slot agar sesuai dengan placeholder Anda. Pemetaan nama yang ada dapat menggabungkan kolom nama depan dan belakang ke dalam variabel name.

Webhook konfigurasi dinamis

Pada jalur webhook konfigurasi pemblokiran, kembalikan agen tersimpan di organisasi Anda beserta nilai per panggilan:

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

Kunci respons menimpa variabel tingkat permintaan, sementara kunci permintaan lainnya tetap ada. Nilai respons null memilih default placeholder. Objek yang digabungkan juga harus muat dalam 32 KB. Respons agen tersimpan hanya menerima agent_id dan variables; kembalikan konfigurasi inline saat Anda perlu mengganti Prompt atau pengaturan. Respons yang berisi prompt selalu menggunakan konfigurasi inline: setiap agent_id dalam respons tersebut diabaikan, termasuk metadata null atau bukan bilangan bulat. Prompt inline tetap harus lolos validasi normal. Respons webhook inline juga dapat menyertakan variables. Respons webhook agen tersimpan menggunakan pembagian A/B agen yang telah di-deploy pada panggilan telepon dan widget; variabel dirender setelah pemilihan varian. Pada panggilan telepon masuk, gunakan nomor tanpa agen masuk yang ditetapkan dan konfigurasikan webhook nomor telepon atau organisasi; kunci widget menggunakan mode="webhook". Notifikasi masuk sistem endpoint tidak menyediakan respons konfigurasi pemblokiran.

POST /v1/widget/session menerima objek variables tingkat atas. Kunci publishable-nya memilih agen tersimpan. Kunci mode webhook meneruskan nilai ini ke webhook konfigurasi dan menggabungkan respons seperti dijelaskan di atas. variables widget/realtime yang diberikan browser dikendalikan oleh klien, diteruskan apa adanya dalam web.incoming setelah validasi dan pembersihan string yang dijelaskan di atas, serta digaungkan ke webhook penyelesaian dan riwayat panggilan. Jangan perlakukan nilai tersebut sebagai data identitas atau otorisasi tepercaya.

POST /v1/realtime/sessions menerima variables bersama agent_id (atau config inline). Ini adalah field API pembuatan sesi. Bridge WebSocket Realtime tidak meneruskan opsi variables; berikan langsung ke API pembuatan sesi. Klien Widget harus menyertakan variables dalam payload sesi yang diposting; penerusan SDK bukan bagian dari perubahan API ini. Panggilan uji mikrofon Builder dan simulasi menyelesaikan default dan placeholder yang hilang, tetapi tidak memiliki input variabel per panggilan.

Nilai yang dikembalikan setelah panggilan

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete, dan web.complete menyertakan variables gabungan akhir serta unresolved_variables. Payload penyelesaian lama yang menyertakan data.history juga menyertakannya:

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

Simpan pengenal CRM atau tugas Anda dalam objek variabel untuk menghubungkan kembali panggilan yang selesai ke catatan sumbernya. Field ini disimpan bersama catatan panggilan; hanya kirim informasi yang sesuai untuk disimpan dalam riwayat panggilan dan webhook.

Kompatibilitas Prompt yang ada

Perenderan juga berlaku untuk Prompt agen tersimpan dan varian A/B yang ada, konfigurasi outbound dan realtime inline, serta Prompt yang dikembalikan oleh webhook konfigurasi. Placeholder {{name}} yang tidak dikenal menjadi teks kosong, bahkan ketika tidak ada variables yang diberikan. Periksa Prompt yang ada sebelum peluncuran, termasuk Prompt inline/webhook yang disediakan secara eksternal dan tidak dapat diinventarisasi oleh ThunderPhone. Panggilan mikrofon Builder dan simulasi menerapkan perilaku default/kosong yang sama.