---
title: "Variabel dan konteks per panggilan"
description: "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.

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

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

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

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

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](/id/guides/pricing) panggilan.

Pada agen [langkah](/id/guides/agent-steps), konteks mengikuti Prompt
setiap agen dalam panggilan, bukan instruksi setiap langkah.

## Asal nilai

### API outbound

Kirim `variables` dan `context` pada `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."
}
```

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.

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

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`](/id/guides/dynamic-call-config) 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](/id/webhooks/call-incoming).
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](/id/guides/sip-addresses), 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](/id/guides/sip-addresses).
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](/id/guides/embed-web-widget)). 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:

```json
{
  "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:

```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` 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](/id/webhooks/call-incoming) 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:

```json
{
  "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](/api-reference/validation-sets),
[proses pemutaran ulang](/api-reference/replay-runs), dan
[penyelidikan](/api-reference/investigations), 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.
