---
title: "Çağrı başına değişkenler ve bağlam"
description: "Ajanı değiştirmeden, her çağrıya istem için adlandırılmış değişkenler veya serbest biçimli bir özet olarak kendi ayrıntılarını verin."
---

Her çağrı, çağrı başına iki tür girdi taşıyabilir. Bunlardan birini veya
ikisini birlikte kullanın:

- **`variables`**: istemdeki `{{placeholders}}` yer tutucularını dolduran adlandırılmış değerlerdir. Arayanın adı, hesap numarası veya randevu zamanı gibi istemin adıyla başvurduğu alanlar için kullanın.
- **`context`**: istemden sonra eklenen serbest biçimli metindir. Bu çağrıdaki görevin açıklaması veya daha önce toplanmış notlar gibi bir şablona uymayan kısa bilgiler için kullanın.

Her ikisi de aşağıda açıklanan çağrı başlatma yöntemlerinin tümünde, kaydedilmiş bir yapay zeka ajanı ve satır içi yapılandırmayla çalışır. Hiçbiri kaydedilmiş yapay zeka ajanını, sürüm geçmişini veya diğer ayarlarını değiştirmez.

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

## Değişkenler

Kaydedilmiş yapay zeka ajanınızın istemine yer tutucular ekleyin, ardından bir çağrı başlatırken
`variables` nesnesini sağlayın. ThunderPhone, çağrı yapılandırmasını ses çalışma zamanına göndermeden önce metni oluşturur.

Değer gerekmediğinde `variables` öğesini atlayın, `null` göndermeyin (`400` ile reddedilir).

### Yer tutucular ve varsayılanlar

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

Adlar büyük/küçük harfe duyarlıdır ve `[A-Za-z_][A-Za-z0-9_]*` biçimini izler. Adın çevresindeki boşluklara izin verilir; `|` sonrasındaki boşluk varsayılanın parçasıdır ve korunur. `{{name|Friend}}`, `name` eksik veya
`null` olduğunda `Friend` değerini kullanır; boş dize açıkça sağlanmış bir değerdir. Varsayılanı olmayan eksik değerler boş dizelere dönüşür ve adları `unresolved_variables` içinde görünür.
Geçerli bir yer tutucu olmayan çift küme parantezler arasındaki metin kaldırılır. Sağlanan her değerin içindeki çift küme parantezli metin bağımsız olarak kaldırılır; bir değer çevresindeki istem metnini veya başka bir değeri kaldıramaz. Eşleşmeyen çift küme parantez ayraçları da kaldırılır. İstemlerdeki JSON örnekleri `{{` kullanmamalıdır.
Değerler düz metindir; hiçbir zaman kod olarak değerlendirilmez veya şablon olarak özyinelemeli biçimde genişletilmez.

Değişkenler ayrıca onay istemlerinde, giden sesli posta mesajlarında ve telefon araması için bu alan gönderildiğinde onay duyurusu metninde görünebilir. Ajanın ayrı bir `first_message` alanı yoktur: açılış talimatlarını isteme ekleyin. Mevcut sesli posta `{agent_name}` ve `{org_name}`
yer tutucuları çalışmaya devam eder.

### Değerler ve sınırlar

Değerler dizeler, sayılar, boole değerleri veya `null` olabilir; boole değerleri `true`
ve `false` olarak işlenir. Yeni satır (`\n`), sekme (`\t`) ve satır başı (`\r`)
dışındaki Unicode denetim (`Cc`) karakterleri; sıfır genişlikli birleştirici
olmayan ve birleştirici karakterler (Hint ve Arap alfabesi kullanan dillerde
sözcükleri oluşturan U+200C, U+200D) dışındaki biçim (`Cf`) karakterleri; ve
vekil (`Cs`) kod noktaları kaldırılır; `\r\n`, `\n` olarak normalleştirilir. Her değer
işlendiğinde 2.000 karakterle sınırlıdır. Sağlanan dizeler depolanmadan önce de
temizlenir ve kısaltılır. Özgün nesne **UTF-8 JSON olarak 32 KB** içine sığmalıdır;
daha büyük nesneler çağrı/oturum isteklerinde `400` alırken kampanya içe
aktarımları geçersiz satırları ayrı ayrı bildirir. Diziler ve iç içe nesneler değer
olarak kabul edilmez. Eşleşmeyen meta veri anahtarları (örneğin boşluk içeren bir CSV
başlığı) korunur ve geri döndürülür, ancak bir yer tutucuyla başvurulamaz.

## Bağlam

`context`, en fazla **20.000 karakter** içeren bir dizedir. ThunderPhone, istemin
değişkenleri doldurulduktan sonra bunu sınırlayıcılarla ayrılmış bir blok olarak
istemden sonra ekler:

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

Ajan bunu talimatlarıyla birlikte okur; bu nedenle çağrı öncesinde bir çalışma
arkadaşınıza bilgi verir gibi yazın. Bağlam bir şablon değildir:
İçindeki `{{name}}` yazıldığı şekilde kalır. Metnin bir değere ihtiyacı varsa,
göndermeden önce değeri kendiniz ekleyin.

- `null`, boş bir dize veya yalnızca boşluk karakterleri bağlam olmadığı anlamına gelir.
- Dize olmayan ya da 20.000 karakterden uzun bir değer, arama ve oturum isteklerinde `400` ile reddedilir; yapılandırma webhook'undan gönderildiğinde ise geçersiz `variables` gibi değişimi başarısız kılar (aşağıya bakın).
- Baştaki ve sondaki boşluk karakterleri kırpılır ve değişken değerlerinde olduğu gibi aynı denetim ve biçim karakterleri kaldırılır.
- Bağlam, aramanın isteminin bir parçasıdır; bu nedenle aramanın [istem boyutuna](/tr/guides/pricing) dahil edilir.

[Adımlar](/tr/guides/agent-steps) kullanan bir ajanda bağlam, her adımın
talimatlarını değil, çağrıdaki her ajanın istemini takip eder.

## Değerlerin kaynakları

### Giden API

`POST /v1/call` üzerinde `variables` ve `context` gönderin:

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

Her ikisi de telefon numarasının varsayılan giden arama ajanıyla veya satır içi bir
`config.prompt` ile çalışır. Satır içi yapılandırmada `context`, yapılandırma webhook'unun
döndürdüğü alanla aynı olan `config` içine de yerleştirilebilir; ikisini de gönderirseniz
aynı metin olmalıdır. Bir idempotency anahtarı farklı değişkenlerle veya farklı bir bağlamla yeniden kullanılamaz.

### Kampanya CSV'si

Telefon dışı CSV sütunları zaten kişi değişkenleri olarak saklanır. Her arama artık bunları otomatik olarak kullanır. Yer tutucularınızla eşleştirmek için `name`, `account_id` ve `appointment_slot` gibi başlıklar kullanın. Mevcut ad eşlemesi, ad ve soyadı sütunlarını `name` değişkeninde birleştirebilir. Kampanya kişilerinin kişi başına bağlamı yoktur.

### Dinamik yapılandırma webhook'u

Engelleyici yapılandırma webhook yolunda, kuruluşunuzda kayıtlı bir ajanı ve çağrı başına değerleri döndürün. Tam çift yönlü bir ajan için, çağrı desteklenen başka bir dilde başlasa bile çağrı ajanın sesini korur:
dil başına ses eşlemeleri ve yerel ses değiştirme bu çağrıya uygulanmaz.

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

Yanıttaki değişkenler istek düzeyindeki değişkenlerin üzerine yazılırken diğer istek
anahtarları korunur. `null` yanıt değeri, yer tutucunun varsayılanını seçer.
Birleştirilmiş nesne de 32 KB sınırına uymalıdır. Kaydedilmiş ajan yanıtları yalnızca
`agent_id`, `variables`, `context`, `language` ve çağrı başına
[`timezone`](/tr/guides/dynamic-call-config) kabul eder; istemi veya diğer ayarları
değiştirmeniz gerektiğinde satır içi yapılandırma döndürün. Kaydedilmiş ajan webhook
yanıtları, hem telefon hem de widget çağrılarında ajanın yayına alınmış A/B dağılımını kullanır;
değişkenler, varyant seçildikten sonra oluşturulur. Yanıt, tam çift yönlü olmayan bir
ajan için `language` ayarladığında, ajan için o dilde bir ses ayarlanmışsa çağrı o
dilin kendi sesini de kullanır. `prompt` içeren bir yanıt her zaman satır içi
yapılandırma kullanır: bu yanıttaki tüm `agent_id` değerleri, null veya tam sayı
olmayan meta veriler dahil olmak üzere yok sayılır. Satır içi istem yine de normal
doğrulamadan geçmelidir. Satır içi webhook yanıtları `variables` ve `context`
de içerebilir. Dize olmayan veya fazla uzun bir `context`, işlemi başarısız kılar: telefon
çağrısı reddedilir ve widget oturumu isteği `400` ile başarısız olur. Kaydedilmiş ajan webhook
yanıtları, hem telefon hem de widget çağrılarında ajanın yayına alınmış A/B dağılımını kullanır;
değişkenler, varyant seçildikten sonra oluşturulur. Gelen telefon çağrılarında, atanmış bir gelen
arama ajanı olmayan bir numara kullanın ve numaranın veya kuruluşun webhook'unu yapılandırın; widget anahtarları
`mode="webhook"` kullanır. Uç nokta sistemi üzerinden gelen bildirimler engelleyici
yapılandırma yanıtları sağlamaz.

### Yapay zeka ajanı çağrı kurulum webhook'u

Bir numarayı yapay zeka ajanına atılı tutmak ve yalnızca çağrıya ait değerleri doldurmak için ajana bir [çağrı kurulum webhook'u](/tr/webhooks/call-incoming) verin.
Bir yapay zeka ajanı bir numarada her gelen çağrıyı yanıtlamadan önce, webhook çağrıyı ve ajanın kimliğini, adını ve sürümünü alır; ardından `agent_id` gerektirmeden yukarıdakiyle aynı `variables`, `context`, `language` ve çağrı başına `timezone` değerleriyle yanıt verir. Ayarlarında varsayılanı olmayan bir yer tutucu kullanan yapay zeka ajanının bir telefon numarasını yanıtlayabilmesi için bu webhook gerekir: webhook başarısız olursa çağrı başlamaz. `{{name|there}}` gibi varsayılanı olan yer tutucular, yapay zeka ajanının webhook olmadan çağrıyı yanıtlamasını sağlar.

### SIP başlıkları

Bir ajana SIP üzerinden ulaşan çağrılar (bir [SIP adresi](/tr/guides/sip-addresses) veya
manuel SIP bağlantısındaki bir numara) `X-*` ve `User-to-User`
başlıklarında bağlam taşıyabilir. Her biri, örneğin
`{{sip_x_amzn_connectcontactid}}` veya `{{sip_uui}}` gibi, en düşük
önceliğe sahip bir `sip_` değişkenine dönüşür: API veya webhook'tan gelen aynı
adlı bir değer önceliklidir. Bkz. [SIP başlıklarında çağrı bağlamı iletme](/tr/guides/sip-addresses).
Başlık değerleri gönderici tarafından ayarlanır; bu nedenle tarayıcı tarafından
sağlanan herhangi bir değer gibi güvenilmez kabul edin.

### Widget oturum API'si

`POST /v1/widget/session`, üst düzey `variables` ve `language` değerlerini kabul eder. Yayınlanabilir anahtarı, kaydedilmiş ajanı seçer. Webhook modundaki anahtarlar bu değerleri yapılandırma webhook'una iletir ve yanıtı yukarıda açıklandığı şekilde birleştirir.
Tarayıcı tarafından sağlanan widget `variables` değerleri istemci tarafından kontrol edilir, yukarıda açıklanan doğrulama ve dize temizleme işlemlerinden sonra `web.incoming` içinde aynen iletilir ve tamamlama webhook'larına ve çağrı geçmişine yansıtılır. Bunları güvenilir kimlik veya yetkilendirme verileri olarak değerlendirmeyin.

Widget'ın kendi tarayıcı `context` alanı farklıdır: ziyaretçinin bulunduğu
sayfadaki metni taşır ve ajan bunu web sitesi içeriği olarak ele alır
([Web widget'ını yerleştirme](/tr/guides/embed-web-widget) bölümüne bakın). Bir widget
çağrısının çağrı başına bağlamı, yukarıda açıklandığı gibi webhook modu anahtarının
yapılandırma webhook'undan gelir. Bir çağrıda her ikisi de varsa önce çağrı başına
bağlam, ardından sayfa içeriği gelir.

### Gerçek zamanlı oturum API'si

`POST /v1/realtime/sessions`, `agent_id` veya satır içi `config` ile birlikte üst düzey `variables`, `context` ve `language` alanlarını kabul eder:

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}
```

`context` yalnızca üst düzeyde yer alır; satır içi bir `config` bunu bilinmeyen
bir alan olarak reddeder.

### Gerçek zamanlı WebSocket

Kaydedilmiş bir ajanla, kaydedilmiş ajanın yayına alınmış istemi kendi istemi olarak kalır.
`session.instructions` çağrının bağlamı olur, `session.prompt.variables`
(veya `session.config.variables`) değişkenleri olur ve `session.language`
çağrı başına dili olur. İlk `session.update` içinde ajanı
`session.prompt.id` ile seçin; bu güncelleme ulaştığında oturum başlar:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}
```

Bağlantı URL'sindeki `?agent_id=12`, soket bağlanır bağlanmaz, herhangi bir
`session.update` öncesinde yapay zeka ajanını başlatır; bu nedenle çağrı başına
girdi taşımaz. İlk `session.update` için beklemek ve onun yönergelerini ve
değişkenlerini kullanmak üzere `&wait_for_session_update=1` ekleyin.

Satır içi bir oturumda (kaydedilmiş ajan yoksa) `session.instructions`, eskiden olduğu gibi istemin kendisidir. Tarayıcı test aramaları ve simülasyonlar, varsayılanları ve eksik yer tutucuları çözümler. Değerlerle test etmek için ajana bir [arama kurulumu örneği](/tr/webhooks/call-incoming) kaydedin ve testi başlatırken bu örneği seçin; arama, arama kurulumu web kancanız bu örnekle yanıt vermiş gibi çalışır.

## Aramadan sonra

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` ve `web.complete`, nihai
birleştirilmiş `variables` ve `unresolved_variables` değerlerini içerir. `data.history` içeren eski
tamamlama yükleri de bunları içerir:

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

Aramanın `prompt_snapshot` öğesi (`GET /v1/calls/{call_id}`), yapay zeka ajanının
değişkenleri doldurulmuş ve bağlam bloğu eklenmiş istemini gösterir.

Tamamlanan aramayı kaynak kaydına bağlamak için CRM veya görev tanımlayıcınızı
değişkenler nesnesinde saklayın. Değişkenler ve bağlam, arama kaydıyla birlikte
saklanır; yalnızca arama geçmişinde ve web kancalarında saklanması uygun olan
bilgileri gönderin.

Bir aramanın [doğrulama kümelerindeki](/api-reference/validation-sets),
[yeniden oynatma çalıştırmalarındaki](/api-reference/replay-runs) ve
[incelemelerdeki](/api-reference/investigations) yeniden oynatmaları, test
edilen istemle birlikte o aramanın değişkenlerini ve bağlamını kullanır. Böylece
bir yeniden oynatma, o aramadaki yapay zeka ajanına ne söylenmiş olacağını test eder.

## Mevcut istemlerle uyumluluk

İşleme, mevcut kaydedilmiş yapay zeka ajanı ve A/B varyant istemlerine, satır içi giden arama ve gerçek zamanlı yapılandırmalara ve yapılandırma web kancalarının döndürdüğü istemlere de uygulanır. Bilinmeyen `{{name}}` yer tutucuları, `variables` sağlanmasa bile boş metne dönüşür. ThunderPhone'un envanterini çıkaramadığı, harici olarak sağlanan satır içi/web kancası istemleri dahil olmak üzere, yayına alma öncesinde mevcut istemleri kontrol edin. Kaydedilmiş bir arama kurulumu örneği seçmediğiniz sürece tarayıcı test aramaları ve simülasyonlar da aynı varsayılan/boş davranışı uygular.
