Developer cookbook

Variabili per chiamata

Personalizza un agente salvato per ogni chiamata senza modificare il prompt, gli strumenti o le impostazioni distribuiti.

Inserisci i segnaposto nel prompt del tuo agente salvato, quindi fornisci un oggetto variables all'avvio di una chiamata. La configurazione salvata e la cronologia delle versioni restano invariate. 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.

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), tutti i caratteri di formato (Cf) e i punti di codice surrogati (Cs) vengono rimossi; \r\n viene normalizzato in \n. Ogni valore è limitato a 2.000 caratteri durante il rendering. 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.

Origine dei valori#

API in uscita#

Invia variables insieme ad agent_id in POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Funziona anche con l'agente in uscita predefinito del numero di telefono o con un config.prompt inline. Una chiave di idempotenza non può essere riutilizzata con variabili diverse.

CSV della campagna#

Le colonne CSV non telefoniche sono già archiviate come variabili di contatto. Ogni chiamata le utilizza automaticamente. Usa intestazioni come name, account_id e appointment_slot in modo che corrispondano ai tuoi segnaposto. La mappatura esistente del nome può combinare le colonne del nome e del cognome nella variabile name.

Webhook di configurazione dinamica#

Nel percorso webhook di configurazione bloccante, restituisci un agente salvato nella tua organizzazione insieme a eventuali valori per chiamata:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Le chiavi 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. Anche l'oggetto unito deve rientrare in 32 KB. Le risposte con agente salvato accettano solo agent_id e variables; restituisci una configurazione inline quando devi sostituire il prompt o le impostazioni. Una risposta contenente prompt usa sempre la configurazione inline: qualsiasi agent_id in quella 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. Le risposte webhook con agente salvato usano la suddivisione A/B distribuita dell'agente sia nelle chiamate telefoniche sia nelle chiamate widget; le variabili vengono elaborate dopo la selezione della variante. Per le chiamate telefoniche in entrata, usa un numero senza agente in entrata assegnato e configura il relativo webhook del numero di telefono o dell'organizzazione; le chiavi widget usano mode="webhook". Le notifiche in entrata del sistema endpoint non forniscono risposte di configurazione bloccanti.

API di sessione Widget e Realtime#

POST /v1/widget/session accetta un oggetto variables di primo livello. La sua 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 di widget/realtime fornite dal browser sono controllate dal client, inoltrate testualmente in web.incoming dopo la convalida e la pulizia delle stringhe descritte sopra, e ripetute nei webhook di completamento e nella cronologia delle chiamate. Non trattarle come dati attendibili di identità o autorizzazione.

POST /v1/realtime/sessions accetta variables insieme ad agent_id (o a una config inline). Questi sono campi dell'API di creazione della sessione. Il bridge WebSocket Realtime non inoltra un'opzione variables; forniscila direttamente all'API di creazione della sessione. I client widget devono includere variables nel payload della sessione inviato; l'inoltro SDK non fa parte di questa modifica API. Le chiamate di test con microfono e simulate in Builder risolvono i valori predefiniti e i segnaposto mancanti, ma non hanno un input di variabili per chiamata.

Valori restituiti 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"]
}

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

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 del rilascio, inclusi i prompt inline/webhook forniti esternamente che ThunderPhone non può inventariare. Le chiamate del microfono Builder e di simulazione applicano lo stesso comportamento predefinito/vuoto.