Azioni e strumenti

La scheda Actions è dove gestisci tutto ciò che il tuo agente può fare oltre la conversazione — strumenti che l'agente chiama durante una conversazione live, hook di prefetch che vengono eseguiti prima dell'inizio della chiamata e azioni post-chiamata che si attivano una volta che la chiamata termina. Le Retrieval Variables (i campi dati che l'agente estrae da ogni conversazione) si trovano nella stessa scheda.

Tutti i piani

Tutti gli strumenti, le azioni e il nuovo hook di pre-fetch sono disponibili su ogni piano, incluso Free.

Le tre fasi

Ogni voce nella scheda Actions appartiene a una delle tre fasi del ciclo di vita. Il menu a discesa Add Tool le raggruppa così è chiaro quando ciascun elemento si attiva:

Fase	Quando	Esempi
Pre fetch	Prima che l'agente saluti	Cerca il chiamante nel tuo CRM per telefono, recupera l'ultimo ordine, ottieni un saluto personalizzato dal tuo backend
Live call	Durante la conversazione, attivato dall'IA quando è il momento giusto	Inoltra la chiamata a un umano, controlla la disponibilità sul calendario, trasferisci a un altro agente, interroga un'API esterna per i dati
Post call	Dopo la fine della chiamata	Invia un'email di riepilogo, attiva una conferma via SMS, invia il payload della chiamata al tuo CRM

Il menu a discesa si apre con Pre fetch in cima perché ogni altra fase ha già molte opzioni — la nuova voce di pre-fetch è la cosa che probabilmente stai cercando.

Pre fetch

Gli hook di pre-fetch permettono al tuo agente di iniziare la chiamata già sapendo chi sta chiamando. Vengono eseguiti in parallelo con la configurazione della chiamata e iniettano la risposta nel system prompt dell'agente prima che venga pronunciata la prima parola.

Quando usarlo

Riconoscere un cliente di ritorno tramite numero di telefono e salutarlo per nome
Recuperare l'ordine aperto del chiamante, l'ultimo appuntamento o il livello di abbonamento
Precaricare il contesto aziendale che dipende da quale linea è stata chiamata
Iniettare note CRM così l'agente conosce la fase e la storia del lead

Come funziona

La piattaforma risolve il telefono del chiamante (dal SIP per le chiamate in entrata, dal numero di destinazione per quelle in uscita).
Ogni azione Pre fetch attiva si attiva in parallelo con un timeout rigido di 1,5 s per richiesta e un budget complessivo di 2 s.
Le risposte riuscite vengono concatenate nel system prompt dell'agente come blocchi denominati — l'agente li legge al suo primissimo turno.
I fallimenti sono silenziosi — un endpoint lento o guasto non blocca mai il saluto. L'agente inizia semplicemente a parlare senza quel blocco.

Configurazione

Campo	Descrizione
Name	Obbligatorio. Etichetta interna e nome del blocco nel prompt — mantienilo breve e descrittivo (es. `crm_lookup`, `vip_check`).
API URL	Obbligatorio. Endpoint da cui recuperare. Supporta i segnaposto `{phone}`, `{direction}`, `{agent_id}`, `{user_id}`, `{call_id}`.
HTTP Method	`GET` è il valore predefinito e più adatto. Funzionano anche `POST` / `PUT` / `PATCH` / `DELETE`.
Headers	Facoltativo. Statici o con template (i segnaposto funzionano anche qui).
Query Parameters	Facoltativo. Precompilato con `phone={phone}` per le nuove azioni di pre-fetch.

Variabili disponibili

Questi token vengono sostituiti in URL, header e parametri query/body al momento della richiesta:

Variabile	Fonte	Valore di esempio
`{phone}`	Telefono del chiamante (E.164) — per le chiamate in uscita, il numero di destinazione	`+431234567890`
`{direction}`	`inbound` o `outbound`	`inbound`
`{agent_id}`	ID interno dell'agente	`65f1a2b3c4...`
`{user_id}`	ID del proprietario del workspace	`65e0b1c2d3...`
`{call_id}`	ID della chiamata (permette al tuo backend di correlare in seguito il payload post-chiamata)	`65f1f2c4d5...`

I segnaposto sconosciuti vengono lasciati verbatim — un template errato non manda mai in crash una chiamata.

Cosa finisce nel prompt

Se il tuo endpoint su https://crm.example.com/lookup?phone={phone} restituisce:

{ "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }

Al system prompt dell'agente viene aggiunto un blocco racchiuso in XML denominato in base all'azione:

<call_context>
  <block name="crm_lookup">
  { "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }
  </block>
</call_context>

Non devi dire all'agente come usarlo — l'LLM coglie il contesto naturalmente. Facoltativamente, menziona il pre-fetch nel tuo system prompt: "If <call_context> contains a customer name, greet them by name."

Vincoli importanti

Solo chiamate telefoniche. Il pre-fetch non viene eseguito per le chiamate da widget (web) — non c'è un numero di telefono su cui applicare il template.
Limite di 8 KB sul corpo della risposta — qualsiasi cosa più lunga viene troncata prima dell'iniezione. Il limite protegge il budget di token del tuo prompt e limita il raggio d'impatto di un endpoint malevolo.
Nessuna valutazione di condition — il pre-fetch si attiva sempre quando è attivo. Non c'è ancora alcuna trascrizione da valutare.

suggerimento

Usa GET con un endpoint di lookup basato sul telefono. Mantieni le risposte piccole e strutturate (oggetto JSON con 3-5 campi). L'agente non ha bisogno del tuo record cliente completo — solo delle parti che cambiano la conversazione.

Strumenti Live Call

Questi vengono eseguiti durante la conversazione. L'IA decide quando chiamare ciascuno strumento in base alla sua descrizione e al dialogo corrente.

Strumenti disponibili

Strumento	Scopo	Quando usarlo
Call Forwarding	Trasferisci a un operatore umano	Il cliente chiede una persona, problemi complessi
Google Calendar	Verifica la disponibilità e prenota appuntamenti	Il cliente vuole fissare una riunione
Outlook Calendar	Lo stesso, via Microsoft Outlook	Il cliente vuole fissare una riunione
API Tool RAG	Recupera dati live da un'API esterna	Servono informazioni in tempo reale (ordini, scorte, stato dell'account)
Agent Transfer	Trasferisci a un altro agente vocale	Il chiamante ha bisogno di un reparto o specialista diverso
HubSpot CRM	Leggi/scrivi contatti e deal in HubSpot	Registrazione della chiamata su HubSpot, ricerca di un lead
MCP servers	Esponi strumenti da uno qualsiasi dei tuoi server MCP registrati	Gestisci un server di strumenti compatibile MCP e vuoi che l'agente usi i suoi strumenti a metà conversazione

Call Forwarding

Trasferisci le chiamate a un umano quando sono soddisfatte condizioni specifiche.

Impostazione	Descrizione	Esempio
Name	Obbligatorio. Nome della persona o del reparto	`"Sales Manager"`
Forwarding Number	Numero di telefono predefinito a cui trasferire	`"+49 123 456 789"`
Trigger Condition	Quando l'agente dovrebbe trasferire	`"Customer asks for manager or issue cannot be resolved"`
Conditional Routing Numbers	Mappatura condizione-numero per l'instradamento	`{"billing": "+49 111 222", "technical": "+49 333 444"}`

Come funziona:

Durante una conversazione, l'IA valuta la Trigger Condition.
Se sono impostati numeri di instradamento condizionale, la condizione corrispondente determina quale numero chiamare.
Altrimenti, viene usato il Forwarding Number.
L'agente informa il chiamante del trasferimento.
La chiamata viene inoltrata — se non c'è risposta, torna all'agente.

suggerimento

Puoi aggiungere più strumenti Call Forwarding per reparti diversi — uno per "Vendite" e un altro per "Assistenza tecnica" con condizioni e numeri diversi.

Google Calendar

Collega il tuo Google Calendar così l'agente può verificare la disponibilità e prenotare appuntamenti durante le chiamate.

Configurazione:

Vai su Integration → Calendars e collega prima il tuo account Google.
Aggiungi lo strumento Google Calendar nella scheda Actions dell'agente.
Seleziona il calendario da usare.
Configura le tue impostazioni di disponibilità.

Impostazione	Descrizione	Predefinito
Calendar	Obbligatorio. Quale calendario usare	Il tuo calendario principale
Timezone	Fuso orario per gli appuntamenti (formato IANA)	Rilevato automaticamente
Work Start Time	Inizio dell'orario di lavoro	9:00
Work End Time	Fine dell'orario di lavoro	18:00
Slot Duration	Durata dell'appuntamento in minuti	30
Working Days	Giorni della settimana disponibili	Lunedì–Venerdì
Buffer Between Appointments	Cuscinetto tra appuntamenti (0–60 min)	0

Durate degli slot supportate: 15, 30, 45, 60, 75, 90, 105, 120 minuti.

suggerimento

Imposta accuratamente i tuoi orari e giorni di lavoro — l'agente proporrà solo fasce orarie all'interno della disponibilità configurata.

Outlook Calendar

Collega il tuo Outlook Calendar per la pianificazione degli appuntamenti durante le chiamate. Funziona allo stesso modo di Google Calendar.

Configurazione:

Vai su Integration → Calendars e collega prima il tuo account Outlook.
Aggiungi lo strumento Outlook Calendar nella scheda Actions dell'agente.
Seleziona il calendario da usare.
Configura le tue impostazioni di disponibilità.

Le impostazioni sono identiche a Google Calendar (fuso orario, orari di lavoro, durata degli slot, giorni lavorativi, buffer).

Agent Transfer

Trasferisci una chiamata a un altro agente vocale del tuo account. Utile quando hai agenti specializzati per reparti diversi.

Impostazione	Descrizione
Target Agent	Obbligatorio. Seleziona a quale agente trasferire
Trigger Condition	Quando trasferire (es. "Caller asks about technical support")

Esempio: Un agente receptionist trasferisce i chiamanti a un agente di vendita quando chiedono i prezzi, o a un agente di assistenza quando hanno un problema tecnico.

HubSpot CRM

Leggi e scrivi nel tuo HubSpot CRM durante la chiamata. Permette all'agente di registrare le interazioni, cercare un contatto per telefono o inviare aggiornamenti di deal senza che tu debba scrivere le chiamate API.

Configurazione:

Vai alla pagina Integrations e collega il tuo account HubSpot.
Aggiungi lo strumento HubSpot CRM nella scheda Actions dell'agente.
Seleziona quale pipeline e quali proprietà l'agente può toccare.

Dopo aver aggiunto lo strumento, l'IA può abbinare il chiamante a un contatto HubSpot tramite telefono, recuperare la fase del deal e aggiornare i campi — tutto dalla conversazione live.

MCP servers

Esponi strumenti da qualsiasi server compatibile MCP che hai collegato a Hanc.AI. Un agente può attingere da più server MCP; un server MCP può servire più agenti.

Configurazione:

Collega il tuo/i tuoi server MCP una volta sotto Integration → MCP servers. Vedi la pagina dedicata Server MCP per i passaggi completi di registrazione.
Aggiungi la voce MCP servers alla scheda Actions di questo agente — è raggruppata sotto Live call nel menu a discesa Add Action.
Attiva quali delle tue connessioni registrate questo agente dovrebbe poter usare.
Aggiungi una breve istruzione "When to use it" così l'agente sa quando ricorrere a questi strumenti.

L'agente riscopre l'insieme di strumenti da ciascun server MCP abilitato all'inizio di ogni chiamata, quindi le modifiche che apporti lato server appaiono automaticamente alla chiamata successiva. Gli strumenti vengono rinominati con l'etichetta della connessione come prefisso così strumenti con nomi simili di server diversi non entrano in collisione.

API Tool RAG

Connettiti ad API esterne per recuperare informazioni in tempo reale durante le chiamate — cerca ordini, controlla l'inventario, verifica account o accedi a qualsiasi dato disponibile via API.

Impostazione	Descrizione	Esempio
Name	Obbligatorio. Nome dello strumento	`"Order Lookup"`
Description / When to Use	Obbligatorio. Quando interrogare l'API	`"Customer asks about order status"`
API URL	Obbligatorio. Endpoint dell'API. Può includere token `{placeholder}` che verranno sostituiti con valori dal Body Parameters Schema (vedi sotto).	`"https://api.yourshop.com/orders/{order_id}"`
HTTP Method	Obbligatorio. Metodo HTTP	`GET`, `POST`, `PUT`, `DELETE`, `PATCH`
Loading Message	Cosa dice l'agente mentre attende	`"Let me check that for you..."`
Timeout	Tempo di attesa massimo (ms)	`5000` (predefinito)
Headers	Header HTTP statici inviati con ogni richiesta	`{"Authorization": "Bearer KEY"}`
Query Parameters	Parametri della query string statici aggiunti a ogni richiesta	`{"apiVersion": "v2"}`
Body Parameters Schema	Obbligatorio. JSON Schema che descrive gli argomenti che l'IA dovrebbe estrarre dalla conversazione e passare allo strumento. Vedi Scrivere il Body Parameters Schema.	Oggetto JSON Schema

suggerimento

Imposta sempre un Loading Message — il silenzio durante le chiamate API sembra un malfunzionamento al chiamante.

note

La vecchia casella "Run on call start" su API Tool RAG è stata sostituita dalla voce dedicata Pre fetch. Usa Pre fetch quando vuoi i dati prima dell'inizio della conversazione; usa API Tool RAG quando l'agente dovrebbe decidere durante la chiamata se recuperare.

Scrivere il Body Parameters Schema

Nonostante il nome, il Body Parameters Schema non è un corpo di richiesta grezzo. È un JSON Schema che descrive cosa l'IA dovrebbe estrarre dalla conversazione e passare al tuo strumento. A seconda del metodo HTTP e del template dell'URL, questi valori finiscono nell'URL, nella query string o nel corpo JSON:

Metodo HTTP	Dove vanno i valori estratti
L'URL contiene `{name}`	Il valore corrispondente viene sostituito nell'URL
`GET`, `DELETE`	I valori rimanenti vengono aggiunti all'URL come `?key=value`
`POST`, `PUT`, `PATCH`	I valori rimanenti vengono inviati come corpo JSON

Struttura minima

{
  "type": "object",
  "properties": {
    "param_name": {
      "type": "string",
      "description": "What this value is and how the AI should pick it"
    }
  },
  "required": ["param_name"]
}

Il type radice è sempre "object". properties elenca ciascun argomento. required indica quali l'IA deve sempre fornire — se il cliente non l'ha ancora detto, l'IA lo chiederà prima di chiamare lo strumento.

Riferimento dei campi

Campo	Scopo
`type`	Tipo JSON del valore: `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"`, `"object"`
`description`	Il più importante. Indica all'IA cosa significa il valore, quale formato usare e quando fornirlo. Aggiungi esempi ogni volta che è possibile.
`enum`	Limita il valore a uno di un elenco fisso. L'IA mapperà il linguaggio naturale sull'opzione più vicina (es. `"the blue one"` → `"blue"`).
`minimum`, `maximum`	Limiti numerici. L'IA rifiuterà/limiterà i valori fuori intervallo.
`default`	Valore usato quando l'IA non passa questo campo. Non obbligatorio, ma documenta il valore implicito.
`format`	Suggerimento di validazione, es. `"email"`, `"date"` (YYYY-MM-DD), `"uri"`.

Esempi

Ricerca prodotto (solo keyword):

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Product search keyword — e.g. \"phone\", \"laptop\", \"Apple\", \"Samsung\""
    }
  },
  "required": ["query"]
}

Usato con l'URL https://dummyjson.com/products/search?q={query}&limit=5 e GET: il valore query finisce nel segnaposto dell'URL. Nulla finisce nel corpo.

Ricerca ordine per ID:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Order ID the customer is asking about, usually 6 to 10 digits. Ask the customer if not provided."
    }
  },
  "required": ["order_id"]
}

Usato con l'URL https://api.example.com/orders/{order_id} e GET.

Prenotazione con più campi obbligatori:

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product ID returned by a previous search_products call."
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "How many items to reserve. Default 1."
    },
    "delivery_method": {
      "type": "string",
      "enum": ["pickup", "home_delivery", "locker"],
      "description": "How the customer wants to receive the item."
    },
    "customer_email": {
      "type": "string",
      "format": "email",
      "description": "Customer's email for order confirmation. Ask if not provided."
    }
  },
  "required": ["product_id", "delivery_method", "customer_email"]
}

Usato con POST https://api.example.com/reservations: i quattro valori finiscono nel corpo JSON. L'IA chiederà al cliente i campi required mancanti prima di chiamare lo strumento.

Strumento senza parametri:

{
  "type": "object",
  "properties": {}
}

Usa questo quando l'endpoint è completamente statico (es. GET /store/hours) e l'IA non deve passare nulla.

Best practice per gli agenti vocali

Mantieni lo schema piatto. Oggetti e array annidati funzionano, ma l'IA può sbagliare quando parla al telefono. Preferisci un massimo di 3–5 campi di primo livello.
Scrivi sempre una description per ogni campo. Includi esempi (e.g. "phone", "laptop") — gli esempi guidano l'IA in modo più affidabile delle definizioni astratte.
Usa enum ogni volta che hai un elenco fisso di valori. Elimina il rischio che l'IA inventi valori o invii "Electronics" invece di "electronics".
Contrassegna un campo come required solo se lo strumento non può funzionare senza di esso. Tutto il resto è facoltativo, e l'IA lo salterà quando il cliente non lo ha menzionato — nessuna domanda extra imbarazzante.
Usa nomi in snake_case e fai corrispondere esattamente i token {placeholder} nell'URL.
Documenta il comportamento per i valori mancanti nella description — es. "Omit if no budget limit", "Default 5".

Azioni Live Messaging

(v2.4) Send SMS live e Send Email live permettono all'agente di inviare un messaggio o un'email a metà chiamata, mentre sta ancora parlando con il chiamante — non solo dopo la fine della chiamata come le loro controparti post-chiamata. Usale per inviare un link, una conferma di prenotazione, un codice o un riepilogo su cui il chiamante può agire prima di riagganciare.

L'IA attiva queste azioni da sola, nel momento, in base alla descrizione dell'azione e alla conversazione — allo stesso modo in cui decide di chiamare qualsiasi altro strumento live.

Azione	Si attiva	Invia a
Send SMS live	Durante la chiamata	Il numero di telefono del chiamante
Send Email live	Durante la chiamata	L'email del chiamante

Limite di invii per chiamata

Ogni canale è limitato a 3 invii per canale per chiamata. Un agente può inviare fino a tre SMS live e fino a tre email live in una singola chiamata; il quarto invio su un canale viene rifiutato. Questo evita che una conversazione prolissa o in loop faccia spam al chiamante.

Matrice dei rifiuti

Un invio live viene rifiutato (e all'agente viene detto il motivo, così può recuperare con eleganza) quando:

Condizione	Risultato
Email non valida o mancante (per Send Email live)	Rifiutato — l'agente chiede al chiamante di confermare la sua email
Telefono non valido o mancante (per Send SMS live)	Rifiutato — l'agente chiede al chiamante di confermare il suo numero
Corpo oltre i 160 caratteri	Rifiutato — il messaggio è troppo lungo per essere inviato così com'è
Limite del canale raggiunto (già 3 invii in questa chiamata)	Rifiutato — nessun ulteriore invio su quel canale

Poiché l'agente riceve il motivo del rifiuto, può risolvere il problema nella conversazione ("Può ripetermi lettera per lettera quell'email?") e riprovare, anziché fallire silenziosamente.

Registrazione sulla timeline CRM

Ogni invio live viene registrato sulla timeline CRM del contatto, così il messaggio che l'agente ha inviato a metà chiamata appare accanto al record della chiamata — puoi vedere esattamente cosa è stato inviato, su quale canale e quando.

Concatenamento intelligente form-canale

Quando un chiamante web invia il modulo del widget con solo alcuni dati di contatto, l'agente usa solo il canale che ha effettivamente:

Il chiamante invia solo un'email → l'agente attiva Send Email live (mai SMS).
Il chiamante invia solo un telefono → l'agente attiva Send SMS live (mai email).
Il chiamante invia entrambi → l'agente può usare entrambi i canali secondo quanto richiede la conversazione.

Questo significa che l'agente non prova mai a mandare un messaggio a un chiamante che ha dato solo un'email, né a inviare un'email a chi ha dato solo un numero — i dati disponibili del modulo determinano quale azione live è a disposizione.

Azioni post-chiamata

Le azioni post-chiamata si attivano una volta terminata la chiamata e dopo che la catena di analisi ha prodotto il riepilogo, il sentiment e le variabili estratte. Consumano i dati della chiamata — non parlano con il cliente.

Azioni disponibili

Azione	Scopo
Send Email	Invia un riepilogo strutturato via email al tuo team o cliente
Send SMS	Conferma via messaggio al chiamante
Send WhatsApp	Messaggio o template WhatsApp (funziona dentro e fuori la finestra di 24 ore)
API Call	Invia il payload completo della chiamata a un'API esterna (CRM, webhook, il tuo data warehouse)

Send Email

Impostazione	Descrizione
Name	Obbligatorio. Identificativo dell'azione
Subject	Obbligatorio. Oggetto dell'email
Message Body	Obbligatorio. Corpo dell'email — può includere variabili di recupero
Trigger Condition	Quando inviare (vuoto = sempre)
Recipients	Obbligatorio. Indirizzi email che ricevono sempre l'email
Conditional Recipients	Mappatura condizione-destinatario

Usare le variabili nell'email:

New lead from phone call:

Name: {{customer_name}}
Email: {{customer_email}}
Interested in: {{selected_plan}}
Notes: {{call_notes}}

Send SMS

Impostazione	Descrizione
Name	Obbligatorio. Identificativo dell'azione
Sender Name	Nome del mittente visualizzato
Message	Obbligatorio. Contenuto dell'SMS (può includere variabili)
Trigger Condition	Quando inviare
Recipients	Obbligatorio. Numeri di telefono che ricevono sempre l'SMS
Conditional Recipients	Mappatura condizione-numero

Send WhatsApp

La messaggistica WhatsApp su HANC usa template pre-approvati da un account Twilio Content centrale — non incolli un Template SID a mano. L'editor dell'azione mostra un menu a discesa di ogni template attualmente attivo e approvato, e ne scegli uno. I segnaposto all'interno del template ({{1}}, {{2}}, …) vengono poi compilati in linea da variabili della chiamata o testo statico che mappi nell'editor.

Impostazione	Descrizione
Name	Obbligatorio. Identificativo dell'azione
Trigger Condition	Quando inviare
Recipients	Obbligatorio. Numeri di telefono che ricevono sempre il messaggio
Conditional Recipients	Mappatura condizione-numero
Template	Obbligatorio. Menu a discesa dei template WhatsApp pre-approvati sincronizzati dall'account Twilio Content centrale. Ogni voce mostra il nome del template, la lingua e un'anteprima del corpo così sai quale scegliere.
Template Variables	Per il template che hai scelto, l'editor elenca ciascun segnaposto (`{{1}}`, `{{2}}`, …) e ti permette di mapparlo a una variabile della chiamata (vedi sotto) o a una stringa statica.

Variabili della chiamata disponibili da mappare nei segnaposto dei template:

Variabile	Descrizione
`{{call_from}}`	Numero di telefono del chiamante
`{{call_to}}`	Numero chiamato
`{{call_summary}}`	Riepilogo della chiamata generato dall'IA
`{{call_sentiment}}`	Sentiment (positivo/neutro/negativo)
`{{call_task_achieved}}`	Se l'obiettivo della chiamata è stato raggiunto
`{{call_transcription}}`	Trascrizione completa della chiamata

Perché un selettore, non testo libero

WhatsApp richiede che ogni messaggio avviato dall'azienda al di fuori della finestra di assistenza clienti di 24 ore usi un template pre-approvato. HANC sincronizza l'elenco dei template approvati dall'account Twilio Content condiviso, così il menu a discesa mostra sempre esattamente ciò che è idoneo all'invio in quel momento — non puoi scegliere per errore una bozza, un template rifiutato o un SID inesistente. Per aggiungere un nuovo template, contatta l'assistenza; una volta approvato da WhatsApp appare automaticamente nel menu a discesa.

API Call

L'azione API Call post-chiamata è il tuo webhook generico verso il resto del tuo stack. Scegli il metodo, imposta l'URL e invieremo l'intero payload della chiamata — il tuo endpoint riceve un oggetto JSON strutturato che descrive cosa è accaduto.

Impostazione	Descrizione
Name	Obbligatorio. Identificativo dell'azione
Trigger Condition	Quando attivarsi (vuoto = ogni chiamata). Valutato da un LLM rispetto alla trascrizione.
API URL	Obbligatorio. URL dell'endpoint dell'API
HTTP Method	Obbligatorio. `GET`, `POST`, `PUT`, `DELETE`, `PATCH`
Headers	Header di richiesta facoltativi
Query Parameters	Parametri della query string facoltativi

Cosa riceve il tuo endpoint

Per POST / PUT / PATCH, il tuo endpoint riceve un oggetto JSON nel corpo della richiesta. I tuoi body param configurati vengono uniti con il payload completo della chiamata:

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "call_summary": "Customer asked about pricing…",
  "task_achieved": true,
  "sentiment": { "sentiment": "positive", "explanation": "…" },
  "custom_analysis_data": {
    "name": "John",
    "email": "john@example.com"
  },
  "collected_data": { /* in-call form submissions */ },
  "transfer_history": [ /* if any agent transfer happened */ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup",
  "is_anonymous": false,
  "is_simulation": false,
  "created_at": 1730000000000,
  "updated_at": 1730000187000
}

Per GET / DELETE, gli stessi campi vengono appiattiti nella query string — ma i valori annidati come transcription, sentiment e custom_analysis_data vengono eliminati (gli URL non possono trasportare dati strutturati in modo sensato). Usa POST/PUT/PATCH se ti serve la trascrizione.

Ogni richiesta riceve anche un header X-Correlation-Id per il tracciamento, e va in timeout dopo 30 secondi.

Pre-fetch vs API Call post-chiamata

Pre fetch applica il template a {phone} ecc. in URL/header/query/body. Restituisce nel prompt, prima della chiamata.
API Call post-chiamata invia l'intero dump della chiamata nel corpo o nella query. Nessun template dell'URL — il tuo endpoint riceve URL statico + corpo dinamico.

Retrieval Variables

Le Retrieval Variables sono campi dati personalizzati che l'IA estrae automaticamente dalle conversazioni. Ad esempio, l'agente può catturare il nome, l'email, il numero di telefono del chiamante o qualsiasi altra informazione tu definisca.

Variabili predefinite

Ogni nuovo agente viene creato con due retrieval variables predefinite:

Variabile	Tipo	Descrizione
Email	Email	Indirizzo email del chiamante
Phone	Phone	Numero di telefono del chiamante

Queste sono abilitate per impostazione predefinita e mostrate nel modulo del widget di chiamata. Puoi modificarle o rimuoverle e aggiungere le tue variabili personalizzate.

Tipi di variabile

Tipo	Caso d'uso	Esempio
Text	Nomi, indirizzi, note, input in formato libero	Nome del cliente, indirizzo di consegna
Number	Quantità, budget, ID	Quantità dell'ordine, importo del budget
Email	Indirizzi email con validazione	Email del cliente
Phone	Numeri di telefono con validazione	Numero di telefono del cliente
Selector	Scelta da opzioni predefinite	Piano preferito (Basic/Pro/Enterprise)
Checkbox	Consenso o conferma sì/no	"Acconsento a ricevere email di marketing"

Configurare una variabile

Campo	Descrizione	Esempio
Variable Name	Obbligatorio. Identificativo della variabile	`customer_email`
Instructions for AI	Obbligatorio. Istruzioni per l'IA su quando e come estrarre questo valore	`"The customer's email address. Ask if not provided."`
Example Format	(Facoltativo) Esempio del formato previsto	`"john@example.com"`
Options (for Selector)	(Solo Selector) Elenco delle opzioni consentite	`["Basic", "Pro", "Enterprise"]`
Show in Form	Se mostrare questo campo nel modulo del widget di chiamata	Abilitato per impostazione predefinita

Show in Form

Quando Show in Form è abilitato, la variabile appare come campo di input visibile nel widget web prima e durante la chiamata. Questo permette ai chiamanti di compilare direttamente le loro informazioni, oltre all'estrazione da parte dell'IA dalla conversazione.

suggerimento

L'IA chiederà naturalmente le informazioni mancanti durante la conversazione. Imposta una descrizione chiara come "Indirizzo email del cliente, chiedilo educatamente se non fornito" e l'agente se ne occuperà.

Aggiungere strumenti e azioni

Vai alla scheda Actions del tuo agente.
Clicca Add Tool.
Scegli la fase giusta dal menu a discesa — Pre fetch, Live call o Post call.
Configura le impostazioni.
Salva — le modifiche si applicano alla chiamata successiva.

Tutte le voci sono elencate insieme nella tabella Actions. Clicca una riga qualsiasi per modificarla, o usa l'icona del cestino per eliminarla.

Correlati

Panoramica degli agenti vocali
Prompt Engineering — Fai riferimento agli strumenti nel tuo prompt
Knowledge Base — Fonti di informazione
Integrazioni — Sistemi esterni con cui i tuoi strumenti possono comunicare

Le tre fasi​

Pre fetch​

Quando usarlo​

Come funziona​

Configurazione​

Variabili disponibili​

Cosa finisce nel prompt​

Vincoli importanti​

Strumenti Live Call​

Strumenti disponibili​

Call Forwarding​

Google Calendar​

Outlook Calendar​

Agent Transfer​

HubSpot CRM​

MCP servers​

API Tool RAG​

Scrivere il Body Parameters Schema​

Struttura minima​

Riferimento dei campi​

Esempi​

Best practice per gli agenti vocali​

Azioni Live Messaging​

Limite di invii per chiamata​

Matrice dei rifiuti​

Registrazione sulla timeline CRM​

Concatenamento intelligente form-canale​

Azioni post-chiamata​

Azioni disponibili​

Send Email​

Send SMS​

Send WhatsApp​

API Call​

Cosa riceve il tuo endpoint​

Retrieval Variables​

Variabili predefinite​

Tipi di variabile​

Configurare una variabile​

Show in Form​

Aggiungere strumenti e azioni​

Correlati​

Le tre fasi

Pre fetch

Quando usarlo

Come funziona

Configurazione

Variabili disponibili

Cosa finisce nel prompt

Vincoli importanti

Strumenti Live Call

Strumenti disponibili

Call Forwarding

Google Calendar

Outlook Calendar

Agent Transfer

HubSpot CRM

MCP servers

API Tool RAG

Scrivere il Body Parameters Schema

Struttura minima

Riferimento dei campi

Esempi

Best practice per gli agenti vocali

Azioni Live Messaging

Limite di invii per chiamata

Matrice dei rifiuti

Registrazione sulla timeline CRM

Concatenamento intelligente form-canale

Azioni post-chiamata

Azioni disponibili

Send Email

Send SMS

Send WhatsApp

API Call

Cosa riceve il tuo endpoint

Retrieval Variables

Variabili predefinite

Tipi di variabile

Configurare una variabile

Show in Form

Aggiungere strumenti e azioni

Correlati