ThunderPhone v3 kini tersedia.Gunakan langsung secara mandiri, mulai 2¢/menit.Baca pengumumannya

Developer cookbook

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 400 pada permintaan panggilan dan sesi; dari webhook konfigurasi, pertukaran gagal seperti variables yang 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.