---
title: "Variabili e contesto per chiamata"
description: "Fornisci a ogni chiamata i propri dettagli, come variabili denominate per il prompt o un brief in formato libero, senza modificare l'agente."
---

Ogni chiamata può includere due tipi di input per chiamata. Usane uno solo o
entrambi insieme:

- **`variables`**: valori denominati che compilano i `{{placeholders}}` nel prompt. Usali
  per i campi a cui il prompt fa riferimento per nome, come il nome del chiamante,
  un numero di conto o una fascia oraria per un appuntamento.
- **`context`**: testo libero aggiunto dopo il prompt. Usalo per un brief che
  non si adatta a un modello, come una descrizione dell'attività per questa chiamata o
  note raccolte in precedenza.

Entrambi funzionano con un agente salvato e con una configurazione inline, in ogni modalità di
avvio di una chiamata descritta di seguito. Nessuno dei due modifica l'agente salvato, la relativa cronologia
delle versioni o le altre impostazioni.

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

## Variabili

Inserisci i segnaposto nel prompt del tuo agente salvato, quindi fornisci un oggetto
`variables` quando avvii una chiamata. ThunderPhone esegue il rendering del testo prima di inviare la
configurazione della chiamata al runtime vocale.

Quando non sono necessari valori, ometti `variables`, non inviare `null` (rifiutato con `400`).

### Segnaposto e valori predefiniti

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

I nomi distinguono tra maiuscole e minuscole e seguono `[A-Za-z_][A-Za-z0-9_]*`. Gli spazi attorno
al nome sono consentiti; lo spazio dopo `|` fa parte del valore predefinito e viene
mantenuto. `{{name|Friend}}` usa `Friend` quando `name` è assente o
`null`; una stringa vuota è un valore fornito esplicitamente. I valori mancanti senza
un valore predefinito diventano stringhe vuote e i relativi nomi appaiono in `unresolved_variables`.
Il testo tra doppie parentesi graffe che non è un segnaposto valido viene rimosso. Il testo tra doppie parentesi graffe
all'interno di ogni valore fornito viene rimosso indipendentemente; un valore non può rimuovere
il testo circostante del prompt o un altro valore. Anche i delimitatori di doppie parentesi graffe
senza corrispondenza vengono rimossi. Gli esempi JSON nei prompt non devono usare `{{`.
I valori sono testo normale, non vengono mai valutati
come codice né espansi ricorsivamente come modelli.

Le variabili possono comparire anche nei prompt di conferma, nei messaggi di segreteria
in uscita e nel testo dell'annuncio di consenso quando quel campo viene inviato per una
chiamata telefonica. L'agente non dispone di un campo `first_message` separato: inserisci
le istruzioni iniziali nel prompt. I segnaposto esistenti della segreteria `{agent_name}` e `{org_name}`
continuano a funzionare.

### Valori e limiti

I valori possono essere stringhe, numeri, booleani o `null`; i booleani vengono visualizzati come `true`
e `false`. I caratteri di controllo Unicode (`Cc`) tranne nuova riga (`\n`), tabulazione (`\t`)
e ritorno a capo (`\r`), i caratteri di formato (`Cf`) tranne il separatore e il
connettore a larghezza zero (U+200C, U+200D, che compongono parole nelle lingue indiane e
con scrittura araba), e i punti di codice surrogati (`Cs`) vengono rimossi; `\r\n`
viene normalizzato in `\n`. Ogni valore
è limitato a 2.000 caratteri quando viene visualizzato. Anche le stringhe fornite vengono pulite e
troncate prima dell'archiviazione. L'oggetto originale deve rientrare in **32 KB di
JSON UTF-8**; gli oggetti più grandi ricevono `400` nelle richieste di chiamata/sessione, mentre
le importazioni di campagne segnalano singolarmente le righe non valide. Gli array e gli oggetti annidati non sono
accettati come valori. Le chiavi dei metadati non corrispondenti (ad esempio un'intestazione CSV con uno
spazio) vengono mantenute e ripetute, ma non possono essere referenziate da un segnaposto.

## Contesto

`context` è una stringa di massimo **20.000 caratteri**. ThunderPhone lo aggiunge dopo
il prompt, una volta compilate le variabili del prompt, come blocco delimitato:

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

L'agente lo legge insieme alle proprie istruzioni, quindi scrivilo come
se dovessi aggiornare un collega prima della chiamata. Il contesto non è un modello:
`{{name}}` al suo interno rimane scritto così com'è. Se il testo richiede un valore, inseriscilo
tu prima dell'invio.

- `null`, una stringa vuota o solo spazi bianchi indicano l'assenza di contesto.
- Un valore che non è una stringa o che supera i 20.000 caratteri viene rifiutato con `400` nelle richieste di chiamata e sessione; da un webhook di configurazione, causa il fallimento dello scambio come `variables` non valide (vedi sotto).
- Gli spazi bianchi iniziali e finali vengono rimossi, così come gli stessi caratteri di controllo e formattazione rimossi dai valori delle variabili.
- Il contesto fa parte del prompt della chiamata, quindi contribuisce alla [dimensione del prompt](/it/guides/pricing) della chiamata.

In un agente con [passaggi](/it/guides/agent-steps), il contesto segue il prompt di
ogni agente nella chiamata, non le istruzioni di ciascun passaggio.

## Origine dei valori

### API in uscita

Invia `variables` e `context` su `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."
}
```

Entrambi funzionano anche con l'agente vocale in uscita predefinito del numero di telefono o con un valore `config.prompt` inline. Con una configurazione inline, `context` può anche essere inserito in `config`, lo stesso campo restituito da un webhook di configurazione; se invii entrambi, devono contenere lo stesso testo. Una chiave di idempotenza non può essere riutilizzata con variabili diverse o un contesto diverso.

### CSV della campagna

Le colonne CSV non telefoniche sono già archiviate come variabili di contatto. Ogni chiamata ora le utilizza automaticamente. Usa intestazioni come `name`, `account_id` e `appointment_slot` per farle corrispondere ai tuoi segnaposto. La mappatura dei nomi esistente può combinare le colonne del nome e del cognome nella variabile `name`. I contatti delle campagne non hanno contesto per singolo contatto.

### Webhook di configurazione dinamica

Nel percorso webhook di configurazione bloccante, restituisci un agente salvato nella tua organizzazione insieme a eventuali valori per chiamata. Per un agente Full duplex, la chiamata mantiene la voce dell'agente anche quando inizia in un'altra lingua supportata: le associazioni vocali per lingua e il cambio di voce nativo non si applicano a quella chiamata.

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

Le variabili della risposta sovrascrivono le variabili a livello di richiesta, mentre le altre
chiavi della richiesta rimangono invariate. Un valore di risposta `null` seleziona il valore predefinito del segnaposto.
L'oggetto unito deve inoltre rientrare in 32 KB. Le risposte dell'agente salvato accettano solo
`agent_id`, `variables`, `context`, `language` e un [`timezone`](/it/guides/dynamic-call-config) per chiamata; restituisci una configurazione inline quando devi
sostituire il prompt o altre impostazioni. Le risposte webhook dell'agente salvato
usano la ripartizione A/B distribuita dell'agente sia per le chiamate telefoniche sia per quelle del widget;
le variabili vengono risolte dopo la selezione della variante. Quando la risposta imposta `language` per un
agente non Full duplex, la chiamata usa anche la voce di quella lingua se
l'agente ne ha una configurata. Una risposta che contiene `prompt` usa sempre una
configurazione inline: qualsiasi `agent_id` in tale risposta viene ignorato, inclusi metadati null o
non interi. Il prompt inline deve comunque superare la normale convalida.
Anche le risposte webhook inline possono includere `variables` e `context`. Un `context`
che non è una stringa o è troppo lungo fa fallire lo scambio: una chiamata telefonica viene
rifiutata e una richiesta di sessione del widget non riesce con `400`. Le risposte webhook dell'agente salvato
usano la ripartizione A/B distribuita dell'agente sia per le chiamate telefoniche sia per quelle del widget;
le variabili vengono risolte dopo la selezione della variante. Per le chiamate telefoniche in entrata, usa un numero senza un
agente in entrata assegnato e configura il relativo webhook del numero di telefono o dell'organizzazione; le chiavi del widget usano
`mode="webhook"`. Le notifiche in entrata del sistema endpoint non forniscono risposte di
configurazione bloccanti.

### Webhook di configurazione della chiamata dell'agente

Per mantenere un numero assegnato al proprio agente e compilare solo i valori della chiamata,
fornisci all'agente un [webhook di configurazione della chiamata](/it/webhooks/call-incoming).
Prima di ogni chiamata in entrata a cui l'agente risponde su un numero, il webhook riceve la
chiamata e l'ID, il nome e la versione dell'agente, quindi risponde con gli stessi
`variables`, `context`, `language` e `timezone` per chiamata indicati sopra, senza richiedere un `agent_id`. Un agente
le cui impostazioni utilizzano un segnaposto senza valore predefinito necessita di questo webhook per rispondere a
un numero di telefono: la chiamata non viene avviata se il webhook non riesce. I segnaposto
con un valore predefinito, come `{{name|there}}`, consentono all'agente di rispondere senza di esso.

### Intestazioni SIP

Le chiamate che raggiungono un agente tramite SIP (un [indirizzo SIP](/it/guides/sip-addresses) o
un numero su una connessione SIP manuale) possono includere contesto nelle intestazioni `X-*` e
`User-to-User`. Ciascuna diventa una variabile `sip_`, ad esempio
`{{sip_x_amzn_connectcontactid}}` o `{{sip_uui}}`, con la precedenza più bassa:
prevale un valore con lo stesso nome proveniente dall'API o da un webhook. Vedi
[Passare il contesto della chiamata nelle intestazioni SIP](/it/guides/sip-addresses).
I valori delle intestazioni sono impostati dal mittente, quindi considerali non attendibili, come qualsiasi
valore fornito dal browser.

### API di sessione del widget

`POST /v1/widget/session` accetta `variables` e `language` di primo livello. La relativa chiave pubblicabile
seleziona l'agente salvato. Le chiavi in modalità webhook inoltrano questi valori al
webhook di configurazione e uniscono la risposta come descritto sopra.
Le `variables` del widget fornite dal browser sono controllate dal client, inoltrate
testualmente in `web.incoming` dopo la convalida e la pulizia delle stringhe descritte
sopra, e riportate nei webhook di completamento e nella cronologia delle chiamate. Non trattarle
come dati attendibili di identità o autorizzazione.

Il campo `context` del browser del widget è diverso: contiene testo dalla
pagina in cui si trova il visitatore, che l'agente tratta come contenuto del sito web (vedi
[Incorpora il widget web](/it/guides/embed-web-widget)). Il contesto per chiamata di una chiamata del widget
proviene dal webhook di configurazione di una chiave in modalità webhook, come sopra. Quando una
chiamata ha entrambi, il contesto per chiamata viene prima, seguito dal contenuto della pagina.

### API di sessione in tempo reale

`POST /v1/realtime/sessions` accetta `variables`, `context` e `language` di primo livello
insieme a `agent_id` o a un elemento `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` va solo al primo livello; un `config` inline lo rifiuta come
campo sconosciuto.

### WebSocket in tempo reale

Con un agente salvato, il prompt distribuito dell'agente salvato rimane il suo prompt.
`session.instructions` diventa il contesto della chiamata, `session.prompt.variables`
(o `session.config.variables`) diventano le sue variabili e `session.language`
diventa la lingua per chiamata. Seleziona l'agente con
`session.prompt.id` nel primo `session.update`, che avvia la sessione quando
arriva l'aggiornamento:

```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` nell'URL di connessione avvia l'agente non appena il socket si
connette, prima di qualsiasi `session.update`, quindi non include input per chiamata. Aggiungi
`&wait_for_session_update=1` per attendere il primo `session.update` e utilizzare le relative
istruzioni e variabili.

In una sessione inline (senza un agente salvato), `session.instructions` è il prompt stesso, come prima. Le chiamate di test nel browser e le simulazioni risolvono i valori predefiniti e i segnaposto mancanti. Per eseguire il test con valori, salva un
[esempio di configurazione della chiamata](/it/webhooks/call-incoming) sull'agente e selezionalo quando avvii il test; la chiamata viene eseguita come se il webhook di configurazione della chiamata avesse risposto con esso.

## Dopo la chiamata

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` e `web.complete` includono le
`variables` finali unite e `unresolved_variables`. Anche i payload di completamento legacy
che includono `data.history` li includono:

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

Il `prompt_snapshot` della chiamata (`GET /v1/calls/{call_id}`) mostra il
prompt dell'agente con le relative variabili compilate e il blocco di contesto aggiunto.

Memorizza l'identificatore del CRM o dell'attività nell'oggetto delle variabili per collegare la
chiamata completata al relativo record di origine. Le variabili e il contesto vengono conservati con il record
della chiamata; invia solo informazioni appropriate da conservare nella cronologia delle chiamate e nei
webhook.

I replay di una chiamata, nei [set di convalida](/api-reference/validation-sets),
nelle [esecuzioni di replay](/api-reference/replay-runs) e
nelle [indagini](/api-reference/investigations), utilizzano le variabili e il
contesto di quella chiamata con il prompt in fase di test, quindi un replay verifica ciò che sarebbe stato comunicato
all'agente durante quella chiamata.

## Compatibilità con i prompt esistenti

Il rendering si applica anche ai prompt esistenti degli agenti salvati e delle varianti A/B, alle configurazioni inline in uscita e in tempo reale e ai prompt restituiti dai webhook di configurazione. I segnaposto `{{name}}` sconosciuti diventano testo vuoto, anche quando non vengono fornite `variables`. Verifica i prompt esistenti prima della distribuzione, inclusi i prompt inline/webhook forniti esternamente che ThunderPhone non può inventariare. Le chiamate di test nel browser e le simulazioni applicano lo stesso comportamento predefinito/testo vuoto, a meno che non selezioni un esempio di configurazione della chiamata salvato.
