Open in
Variabili e contesto per chiamata
Fornisci a ogni chiamata i propri dettagli, come variabili denominate per il prompt o un brief in formato libero, senza modificare l
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.
{
"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
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:
<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
400nelle richieste di chiamata e sessione; da un webhook di configurazione, causa il fallimento dello scambio comevariablesnon 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 della chiamata.
In un agente con passaggi, 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:
{
"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.
{
"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."
}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 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.
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 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.
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). 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:
{
"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:
{
"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 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:
{
"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, nelle esecuzioni di replay e nelle indagini, 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.