Open in
Variabel dan konteks per panggilan
Berikan setiap panggilan detailnya sendiri, sebagai variabel bernama untuk Prompt atau ringkasan bebas, tanpa mengubah agen.
Setiap panggilan dapat membawa dua jenis input per panggilan. Gunakan salah satu, atau keduanya secara bersamaan:
variables: nilai bernama yang mengisi{{placeholders}}dalam Prompt. Gunakan untuk kolom yang dirujuk oleh Prompt berdasarkan nama, seperti nama penelepon, nomor akun, atau slot janji temu.context: teks bentuk bebas yang ditambahkan setelah Prompt. Gunakan untuk ringkasan yang tidak sesuai dengan template, seperti deskripsi tugas untuk panggilan ini atau catatan yang dikumpulkan sebelumnya.
Keduanya berfungsi dengan agen tersimpan dan konfigurasi inline, pada setiap cara memulai panggilan yang dijelaskan di bawah. Keduanya tidak mengubah agen tersimpan, riwayat versinya, atau pengaturan lainnya.
{
"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."
}Variabel
Tempatkan placeholder dalam Prompt agen tersimpan Anda, lalu berikan objek variables
saat memulai panggilan. 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 dan batas
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), karakter format (Cf) selain non-joiner dan joiner
lebar-nol (U+200C, U+200D, yang membentuk kata dalam bahasa Indic dan beraksara
Arab), 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 tidak valid secara terpisah. Array dan objek bersarang tidak
diterima sebagai nilai. Kunci metadata yang tidak sesuai (misalnya header CSV dengan
spasi) tetap disimpan dan dikembalikan, tetapi tidak dapat dirujuk oleh placeholder.
Konteks
context adalah string hingga 20.000 karakter. ThunderPhone menambahkannya setelah
Prompt, setelah variabel Prompt diisi, sebagai blok yang dibatasi:
<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>Agen membacanya bersama instruksinya, jadi tulis seperti Anda
memberi pengarahan kepada rekan sebelum panggilan. Konteks bukan template:
{{name}} di dalamnya tetap seperti tertulis. Jika teks memerlukan nilai, masukkan nilainya
sendiri sebelum mengirimkannya.
null, string kosong, atau hanya spasi berarti tidak ada konteks.- Nilai yang bukan string, atau lebih panjang dari 20.000 karakter,
ditolak dengan
400pada permintaan panggilan dan sesi; dari webhook konfigurasi, pertukaran gagal sepertivariablesyang tidak valid (lihat di bawah). - Spasi di awal dan akhir dihapus, dan karakter kontrol serta format yang sama seperti pada nilai variabel dihapus.
- Konteks adalah bagian dari Prompt panggilan, sehingga diperhitungkan dalam ukuran Prompt panggilan.
Pada agen langkah, konteks mengikuti Prompt setiap agen dalam panggilan, bukan instruksi setiap langkah.
Asal nilai
API outbound
Kirim variables dan context pada 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."
}Keduanya juga berfungsi dengan agen panggilan keluar default nomor telepon, atau dengan config.prompt inline. Dengan konfigurasi inline, context juga dapat ditempatkan di dalam config, yaitu field yang sama yang dikembalikan oleh webhook konfigurasi; jika Anda mengirim keduanya, teksnya harus sama. Kunci idempotensi tidak dapat digunakan kembali dengan variabel yang berbeda atau konteks 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. Kontak kampanye
tidak memiliki konteks per kontak.
Webhook konfigurasi dinamis
Pada jalur webhook konfigurasi yang memblokir, kembalikan agen tersimpan di organisasi Anda beserta nilai per panggilan. Untuk agen Full duplex, panggilan tetap menggunakan suara agen meskipun panggilan dimulai dalam bahasa lain yang didukung: pemetaan suara per bahasa dan peralihan suara native tidak berlaku untuk panggilan tersebut.
{
"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."
}Variabel dalam respons menimpa variabel tingkat permintaan, sementara kunci permintaan lainnya tetap ada. Nilai respons null memilih nilai default placeholder.
Objek yang digabungkan juga harus muat dalam 32 KB. Respons agen tersimpan hanya menerima
agent_id, variables, context, language, dan
timezone per panggilan; kembalikan konfigurasi inline saat Anda perlu
mengganti Prompt atau pengaturan lainnya. Respons webhook agen tersimpan
menggunakan pembagian A/B agen yang di-deploy pada panggilan telepon dan widget;
variabel dirender setelah pemilihan varian. Saat respons menetapkan language untuk
agen non-Full duplex, panggilan juga menggunakan suara bahasa tersebut jika
agen memiliki suara yang ditetapkan untuk bahasa itu. Respons yang berisi prompt selalu menggunakan
konfigurasi inline: setiap agent_id dalam respons tersebut diabaikan, termasuk null atau
metadata non-bilangan bulat. Prompt inline tetap harus lolos validasi normal.
Respons webhook inline juga dapat menyertakan variables dan context. context
yang bukan string atau terlalu panjang menyebabkan pertukaran gagal: panggilan telepon
ditolak, dan permintaan sesi widget gagal dengan 400. Respons webhook agen tersimpan
menggunakan pembagian A/B agen yang di-deploy pada panggilan telepon dan widget;
variabel dirender setelah pemilihan varian. Pada panggilan telepon masuk, gunakan nomor tanpa agen panggilan masuk yang ditetapkan
dan konfigurasikan webhook nomor telepon atau organisasinya; kunci widget menggunakan
mode="webhook". Notifikasi masuk sistem endpoint tidak menyediakan respons konfigurasi pemblokiran.
Webhook penyiapan panggilan agen
Agar nomor tetap ditetapkan ke agennya dan hanya mengisi nilai panggilan, berikan agen tersebut webhook penyiapan panggilan.
Sebelum setiap panggilan masuk dijawab agen pada sebuah nomor, webhook menerima panggilan serta id, nama, dan versi agen, lalu merespons dengan variables, context, language, dan timezone per panggilan yang sama seperti di atas, tanpa memerlukan agent_id. Agen
yang pengaturannya menggunakan placeholder tanpa nilai default memerlukan webhook ini untuk menjawab nomor telepon: panggilan tidak dimulai saat webhook gagal. Placeholder dengan nilai default, seperti {{name|there}}, memungkinkan agen menjawab tanpa webhook tersebut.
Header SIP
Panggilan yang mencapai agen melalui SIP (sebuah alamat SIP, atau
nomor pada koneksi SIP manual) dapat membawa konteks dalam header X-* dan
User-to-User. Masing-masing menjadi variabel sip_, seperti
{{sip_x_amzn_connectcontactid}} atau {{sip_uui}}, dengan
prioritas terendah: nilai dengan nama yang sama dari API atau webhook yang diprioritaskan. Lihat
Teruskan konteks panggilan dalam header SIP.
Nilai header ditetapkan oleh pengirim, jadi perlakukan sebagai tidak tepercaya, seperti nilai apa pun
yang diberikan oleh browser.
API sesi Widget
POST /v1/widget/session menerima variables dan language tingkat atas. Kunci publishable-nya
memilih agen yang tersimpan. Kunci mode webhook meneruskan nilai-nilai ini ke
webhook konfigurasi dan menggabungkan respons seperti dijelaskan di atas.
variables widget yang diberikan oleh browser dikendalikan oleh klien, diteruskan
apa adanya dalam web.incoming setelah validasi dan pembersihan string yang dijelaskan
di atas, serta dicerminkan ke webhook penyelesaian dan riwayat panggilan. Jangan perlakukan nilai tersebut
sebagai data identitas atau otorisasi tepercaya.
Kolom context browser milik Widget berbeda: kolom ini membawa teks dari
halaman yang sedang dikunjungi pengunjung, yang diperlakukan agen sebagai konten situs web (lihat
Sematkan Widget web). Konteks per-panggilan untuk panggilan Widget
berasal dari webhook konfigurasi kunci mode webhook, seperti di atas. Ketika sebuah
panggilan memiliki keduanya, konteks per-panggilan muncul lebih dahulu, lalu konten halaman.
API sesi Realtime
POST /v1/realtime/sessions menerima variables, context, dan language di tingkat teratas
bersama agent_id atau config inline:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context hanya ditempatkan di tingkat atas; config inline menolaknya sebagai
kolom yang tidak dikenal.
WebSocket Realtime
Dengan agen tersimpan, Prompt yang dideploy dari agen tersimpan tetap menjadi Prompt-nya.
session.instructions menjadi konteks panggilan, session.prompt.variables
(atau session.config.variables) menjadi variabelnya, dan session.language
menjadi bahasa per panggilannya. Pilih agen dengan
session.prompt.id dalam session.update pertama, yang memulai sesi setelah
pembaruan tersebut diterima:
{
"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 pada URL koneksi memulai agen segera setelah soket
terhubung, sebelum session.update apa pun, sehingga tidak membawa input per panggilan. Tambahkan
&wait_for_session_update=1 untuk menunggu session.update pertama dan menggunakan
instruksi serta variabelnya.
Dalam sesi inline (tanpa agen tersimpan), session.instructions adalah Prompt itu sendiri, seperti sebelumnya. Panggilan uji browser dan simulasi menyelesaikan nilai default serta placeholder yang belum diisi. Untuk menguji dengan nilai, simpan
contoh penyiapan panggilan pada
agen dan pilih saat Anda memulai pengujian; panggilan berjalan seolah webhook
penyiapan panggilan Anda telah menjawab dengannya.
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"]
}prompt_snapshot panggilan (GET /v1/calls/{call_id}) menampilkan Prompt agen
dengan variabelnya terisi dan blok konteks ditambahkan.
Simpan pengenal CRM atau tugas Anda dalam objek variabel untuk menghubungkan kembali panggilan yang selesai ke catatan sumbernya. Variabel dan konteks disimpan bersama catatan panggilan; hanya kirim informasi yang sesuai untuk disimpan dalam riwayat panggilan dan webhook.
Pemutaran ulang panggilan, dalam set validasi, proses pemutaran ulang, dan penyelidikan, menggunakan variabel dan konteks panggilan tersebut dengan Prompt yang diuji, sehingga pemutaran ulang menguji apa yang akan diberitahukan kepada agen pada panggilan tersebut.
Kompatibilitas Prompt yang ada
Perenderan juga berlaku untuk Prompt agen tersimpan dan varian A/B yang sudah 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 disediakan. Periksa Prompt yang ada sebelum peluncuran, termasuk Prompt inline/webhook yang disediakan secara eksternal dan tidak dapat diinventarisasi oleh ThunderPhone. Panggilan uji browser dan simulasi menerapkan perilaku default/kosong yang sama, kecuali Anda memilih sampel pengaturan panggilan tersimpan.