ThunderPhone v3 è online.Attivazione self-service, da 2¢/min.Leggi l’annuncio

Developer cookbook

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