---
title: "Variabile și context pentru fiecare apel"
description: "Oferiți fiecărui apel propriile detalii, ca variabile denumite pentru prompt sau ca rezumat în format liber, fără a modifica agentul."
---

Fiecare apel poate include două tipuri de date de intrare pentru apel. Folosiți unul dintre ele sau ambele împreună:

- **`variables`**: valori denumite care completează `{{placeholders}}` din prompt. Folosiți-le pentru câmpurile la care promptul se referă după nume, cum ar fi numele apelantului, un număr de cont sau un interval pentru programare.
- **`context`**: text liber adăugat după prompt. Folosiți-l pentru un rezumat care nu se potrivește într-un șablon, cum ar fi o descriere a sarcinii pentru acest apel sau note colectate anterior.

Ambele funcționează cu un agent salvat și cu o configurație inline, pentru toate modalitățile de inițiere a unui apel descrise mai jos. Niciunul nu modifică agentul salvat, istoricul versiunilor acestuia sau celelalte setări ale sale.

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

## Variabile

Introduceți substituenți în promptul agentului salvat, apoi furnizați un obiect `variables`
când inițiați un apel. ThunderPhone redă textul înainte de a trimite
configurația apelului către timpul de execuție vocal.

Când nu sunt necesare valori, omiteți `variables`; nu trimiteți `null` (respins cu `400`).

### Substituenți și valori implicite

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

Numele sunt sensibile la majuscule și minuscule și respectă `[A-Za-z_][A-Za-z0-9_]*`. Spațiile albe din jurul
numelui sunt permise; spațiile albe de după `|` fac parte din valoarea implicită și sunt
păstrate. `{{name|Friend}}` utilizează `Friend` când lipsește `name` sau are valoarea
`null`; un șir gol este o valoare furnizată explicit. Valorile lipsă fără
o valoare implicită devin șiruri goale, iar numele lor apar în `unresolved_variables`.
Textul dintre acolade duble care nu este un substituent valid este eliminat. Textul dintre acolade duble
din fiecare valoare furnizată este eliminat independent; o valoare nu poate elimina
textul din jur din prompt sau o altă valoare. Delimitatorii de acolade duble
nepereche sunt, de asemenea, eliminați. Exemplele JSON din prompturi nu trebuie să utilizeze `{{`.
Valorile sunt text simplu, nu sunt niciodată evaluate
ca cod și nu sunt extinse recursiv ca șabloane.

Variabilele pot apărea și în prompturile de confirmare, mesajele vocale
trimise și textul anunțului de consimțământ atunci când acel câmp este trimis pentru un
apel telefonic. Agentul nu are un câmp `first_message` separat: includeți
instrucțiunile de deschidere în prompt. Substituenții existenți pentru mesageria vocală `{agent_name}` și `{org_name}`
continuă să funcționeze.

### Valori și limite

Valorile pot fi șiruri de caractere, numere, valori booleene sau `null`; valorile booleene sunt redate ca `true`
și `false`. Caracterele de control Unicode (`Cc`), cu excepția liniei noi (`\n`), tabulatorului (`\t`)
și returului de car (`\r`), caracterele de formatare (`Cf`), cu excepția caracterelor de nealipire și alipire cu lățime zero (U+200C, U+200D, care scriu cuvinte în limbile indică și în limbile cu scriere arabă), precum și punctele de cod surogat (`Cs`) sunt eliminate; `\r\n`
este normalizat la `\n`. Fiecare valoare
este limitată la 2.000 de caractere la redare. Șirurile furnizate sunt, de asemenea, curățate și
trunchiate înainte de stocare. Obiectul original trebuie să încapă în **32 KB de
JSON UTF-8**; obiectele mai mari primesc `400` la solicitările de apel/sesiune, iar
importurile de campanii raportează individual rândurile nevalide. Matricele și obiectele imbricate nu sunt
acceptate ca valori. Cheile de metadate neconforme (de exemplu, un antet CSV cu un
spațiu) sunt păstrate și retransmise, dar nu pot fi referite printr-un substituent.

## Context

`context` este un șir de până la **20.000 de caractere**. ThunderPhone îl adaugă după
prompt, după ce sunt completate variabilele promptului, ca bloc delimitat:

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

Agentul îl citește împreună cu instrucțiunile sale, așa că scrieți-l așa cum
ați informa un coleg înainte de apel. Contextul nu este un șablon:
`{{name}}` din interiorul lui rămâne exact cum este scris. Dacă textul necesită o valoare, introduceți valoarea
dumneavoastră înainte de trimitere.

- `null`, un șir gol sau doar spații albe înseamnă că nu există context.
- O valoare care nu este un șir sau care depășește 20.000 de caractere este respinsă cu `400` în solicitările de apel și sesiune; dintr-un webhook de configurare, eșuează schimbul de date la fel ca `variables` nevalid (vedeți mai jos).
- Spațiile albe de la început și de la sfârșit sunt eliminate, iar aceleași caractere de control și de formatare ca din valorile variabilelor sunt eliminate.
- Contextul face parte din promptul apelului, așadar este luat în calcul în [dimensiunea promptului](/ro/guides/pricing) apelului.

Pentru un agent cu [pași](/ro/guides/agent-steps), contextul urmează promptul
fiecărui agent din apel, nu instrucțiunile fiecărui pas.

## De unde provin valorile

### API pentru apeluri ieșite

Trimiteți `variables` și `context` în `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."
}
```

Ambele funcționează și cu agentul vocal implicit pentru apeluri efectuate al numărului de telefon sau cu un `config.prompt` integrat. Cu o configurație integrată, `context` poate fi inclus și în `config`, același câmp returnat de un webhook de configurare; dacă le trimiteți pe ambele, acestea trebuie să conțină același text. O cheie de idempotentizare nu poate fi reutilizată cu variabile diferite sau cu un context diferit.

### CSV de campanie

Coloanele CSV care nu conțin numere de telefon sunt deja stocate ca variabile de contact. Fiecare apelare le utilizează acum automat. Folosiți antete precum `name`, `account_id` și `appointment_slot` pentru a corespunde substituenților dumneavoastră. Maparea existentă a numelui poate combina coloanele pentru prenume și nume de familie în variabila `name`. Contactele din campanii nu au context per contact.

### Webhook de configurare dinamică

Pe ruta webhookului de configurare blocant, returnați un agent salvat din organizația dumneavoastră împreună cu orice valori per apel. Pentru un agent Full duplex, apelul păstrează vocea agentului chiar și atunci când apelul începe într-o altă limbă acceptată: mapările vocilor pe limbă și comutarea nativă a vocii nu se aplică acelui apel.

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

Variabilele din răspuns suprascriu variabilele de la nivelul cererii, în timp ce celelalte
chei ale cererii rămân neschimbate. O valoare de răspuns `null` selectează valoarea implicită a substituentului.
Obiectul combinat trebuie, de asemenea, să se încadreze în 32 KB. Răspunsurile pentru agenți salvați acceptă numai
`agent_id`, `variables`, `context`, `language` și un
[`timezone`](/ro/guides/dynamic-call-config) per apel; returnați o configurație inline atunci când trebuie să
înlocuiți promptul sau alte setări. Răspunsurile webhook pentru agenți salvați
folosesc împărțirea A/B implementată a agentului atât pentru apelurile telefonice, cât și pentru cele din widget;
variabilele sunt randate după selectarea variantei. Când răspunsul setează `language` pentru un
agent care nu este Full duplex, apelul folosește și vocea proprie a limbii respective, dacă
agentul are una configurată pentru aceasta. Un răspuns care conține `prompt` folosește întotdeauna
configurația inline: orice `agent_id` din acel răspuns este ignorat, inclusiv metadatele nule sau
care nu sunt numere întregi. Promptul inline trebuie în continuare să treacă validarea normală.
Răspunsurile webhook inline pot include și `variables` și `context`. Un `context`
care nu este un șir de caractere sau este prea lung face ca schimbul să eșueze: un apel telefonic este
respins, iar o cerere de sesiune widget eșuează cu `400`. Răspunsurile webhook pentru agenți salvați
folosesc împărțirea A/B implementată a agentului atât pentru apelurile telefonice, cât și pentru cele din widget;
variabilele sunt randate după selectarea variantei. Pentru apelurile telefonice primite, utilizați un număr căruia nu îi este atribuit niciun
agent pentru apeluri primite și configurați webhook-ul numărului de telefon sau al organizației; cheile widget folosesc
`mode="webhook"`. Notificările primite de la sistemul de endpointuri nu furnizează răspunsuri de configurare blocante.

### Webhook de configurare a apelului pentru agent

Pentru a păstra un număr atribuit agentului său și a completa numai valorile apelului, configurați pentru agent un [webhook de configurare a apelului](/ro/webhooks/call-incoming).
Înainte ca agentul să răspundă la fiecare apel de intrare pe un număr, webhookul primește apelul și ID-ul, numele și versiunea agentului și răspunde cu aceleași `variables`, `context`, `language` și `timezone` pentru fiecare apel ca mai sus, fără a necesita un `agent_id`. Un agent
ale cărui setări utilizează un substituent fără valoare implicită are nevoie de acest webhook pentru a răspunde la un număr de telefon: apelul nu începe dacă webhookul eșuează. Substituenții cu o valoare implicită, cum ar fi `{{name|there}}`, permit agentului să răspundă fără acesta.

### Antete SIP

Apelurile care ajung la un agent vocal prin SIP (o [adresă SIP](/ro/guides/sip-addresses) sau
un număr într-o conexiune SIP manuală) pot include context în antetele `X-*` și
`User-to-User`. Fiecare devine o variabilă `sip_`, precum
`{{sip_x_amzn_connectcontactid}}` sau `{{sip_uui}}`, cu cea mai mică
prioritate: prevalează o valoare cu același nume din API sau dintr-un webhook. Consultați
[Transmiterea contextului apelului în antete SIP](/ro/guides/sip-addresses).
Valorile antetelor sunt setate de expeditor, așa că tratați-le ca nefiabile, la fel ca orice
valoare furnizată de browser.

### API pentru sesiuni widget

`POST /v1/widget/session` acceptă `variables` și `language` la nivel superior. Cheia sa publicabilă
selectează agentul salvat. Cheile în modul webhook redirecționează aceste valori către
webhookul de configurare și îmbină răspunsul conform descrierii de mai sus.
`variables` ale widgetului furnizate de browser sunt controlate de client, redirecționate
verbatim în `web.incoming` după validarea și curățarea șirurilor descrise
mai sus și replicate în webhookurile de finalizare și în istoricul apelurilor. Nu le tratați
ca date de identitate sau autorizare de încredere.

Câmpul `context` al browserului propriului widget este diferit: acesta transportă text de pe
pagina pe care se află vizitatorul, pe care agentul îl tratează ca conținut de site web (vedeți
[Integrarea widgetului web](/ro/guides/embed-web-widget)). Contextul per apel al unui apel din widget
provine din webhookul de configurare al unei chei în modul webhook, conform celor de mai sus. Când un
apel le are pe ambele, contextul per apel este primul, urmat de conținutul paginii.

### API pentru sesiuni în timp real

`POST /v1/realtime/sessions` acceptă `variables`, `context` și `language` la nivel superior, alături de `agent_id` sau de o `config` integrată:

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

`context` este permis numai la nivel superior; un `config` inline îl respinge ca
câmp necunoscut.

### WebSocket în timp real

Cu un agent salvat, promptul implementat al agentului salvat rămâne promptul său.
`session.instructions` devine contextul apelului, `session.prompt.variables`
(sau `session.config.variables`) devin variabilele sale, iar `session.language`
devine limba sa pentru fiecare apel. Selectați agentul cu
`session.prompt.id` în primul `session.update`, care pornește sesiunea odată ce
sosește acea actualizare:

```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` în URL-ul conexiunii pornește agentul imediat ce socketul se
conectează, înainte de orice `session.update`, astfel încât nu include date de
intrare pentru fiecare apel. Adăugați `&wait_for_session_update=1` pentru a aștepta primul `session.update` și a utiliza instrucțiunile și variabilele acestuia.

Într-o sesiune inline (fără agent salvat), `session.instructions` este promptul propriu-zis, ca înainte. Apelurile de test din browser și simulările rezolvă valorile implicite și substituenții lipsă. Pentru a testa cu valori, salvați un
[exemplu de configurare a apelului](/ro/webhooks/call-incoming) în agent și selectați-l când porniți testul; apelul rulează ca și cum webhookul dumneavoastră de configurare a apelului ar fi răspuns cu acesta.

## După apel

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` și `web.complete` includ
valorile finale fuzionate `variables` și `unresolved_variables`. Încărcăturile utile vechi de finalizare
care includ `data.history` le includ și pe acestea:

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

`prompt_snapshot` al apelului (`GET /v1/calls/{call_id}`) afișează promptul
agentului, cu variabilele completate și blocul de context adăugat.

Stocați identificatorul CRM sau al sarcinii în obiectul de variabile pentru a
asocia apelul finalizat cu înregistrarea sa sursă. Variabilele și contextul sunt
păstrate împreună cu înregistrarea apelului; trimiteți doar informații adecvate
pentru păstrarea în istoricul apelurilor și în webhookuri.

Reluările unui apel, în [seturi de validare](/api-reference/validation-sets),
[execuții de reluare](/api-reference/replay-runs) și
[analize](/api-reference/investigations), utilizează variabilele și contextul
acelui apel împreună cu promptul testat, astfel încât o reluare testează ce i
s-ar fi transmis agentului în acel apel.

## Compatibilitate cu prompturile existente

Redarea se aplică și prompturilor existente pentru agenți salvați și variante A/B, configurațiilor inline pentru apeluri efectuate și în timp real, precum și prompturilor returnate de webhookurile de configurare. Substituenții necunoscuți `{{name}}` devin text gol, chiar și atunci când nu sunt furnizate `variables`. Verificați prompturile existente înainte de lansare, inclusiv prompturile inline/webhook furnizate extern, pe care ThunderPhone nu le poate inventaria. Apelurile de test din browser și simulările aplică același comportament implicit/de text gol, cu excepția cazului în care alegeți un eșantion de configurare a apelului salvat.
