Definizione
Un webhook è una richiesta HTTP che un sistema invia a un URL di un altro sistema quando accade qualcosa o serve qualcosa. In un agente vocale, uno strumento webhook è il modo in cui l'agente chiama il proprio endpoint durante una chiamata.
Come funziona un webhook
La maggior parte delle API aspetta di essere interrogata. Un webhook capovolge la cosa: il sistema mittente fa una richiesta HTTP a un indirizzo che gli è stato indicato. Il ricevente espone un URL, il mittente lo chiama con un metodo come POST, un insieme di intestazioni e un corpo, e il ricevente risponde con un codice di stato.
I webhook compaiono nelle piattaforme vocali in due modi.
- Callback di eventi. La piattaforma notifica al server qualcosa che è successo, come la fine di una chiamata, così da poter archiviare una trascrizione o aggiornare un record.
- Strumenti webhook. L’agente chiama il suo endpoint a metà di una chiamata, per consultare qualcosa o fare qualcosa, e usa la risposta. È una forma di chiamata a strumenti.
Nei Managed Agents di Cartesia, uno strumento webhook è definito con un URL, un metodo HTTP, parametri, intestazioni e autenticazione. Cartesia documenta questi comportamenti:
- L’URL deve essere HTTPS.
- Il modello decide quando chiamarlo in base alla descrizione dello strumento.
- Ogni parametro è compilato dal modello, da un valore fisso o da una variabile dinamica.
- Il timeout della richiesta è di 20 secondi per impostazione predefinita.
- Un timeout, un endpoint irraggiungibile o uno stato diverso da 2xx restituisce un risultato di errore al modello, e la chiamata continua.
Perché conta per gli agenti vocali
Un webhook è il collegamento tra la conversazione e i suoi sistemi, quindi il suo comportamento si sente. Un endpoint lento crea silenzio. Un endpoint che fallisce restituisce un errore di cui il modello deve parlare, quindi il corpo della risposta deve dire cosa è andato storto con parole che l’agente può usare.
Si progetti il lato ricevente come se chi chiama stesse guardando. Si restituisca testo breve e semplice, perché un lungo dump JSON costa al modello tempo di lettura. Si rendano sicure da ripetere le operazioni che modificano dati, poiché un nuovo tentativo o una richiesta duplicata del modello non deve prenotare due appuntamenti. Si autentichi la richiesta e si verifichi ogni parametro sul proprio server, perché i valori forniti dal modello provengono da una conversazione con uno sconosciuto.
Si imposti il timeout rispetto alla pausa che chi chiama accetterà. Un timeout di 20 secondi è lungo da passare in silenzio durante una chiamata, quindi si abbinino gli strumenti lenti a una frase detta prima della loro esecuzione.
Esempio
Uno strumento webhook illustrativo per una linea ordini:
- Metodo e URL: GET
https://api.example.com/orders/{order_id} - Descrizione: «Consulta lo stato di un ordine in base al suo numero.»
- Risposta: «Spedito martedì, arriva venerdì.»
Il modello compila order_id con quanto ha detto chi chiama e pronuncia la risposta con parole proprie.