In una chiamata web (il widget, la pagina ospitata, la tua app) chi chiama vede una chat accanto alla voce, quindi l'agente può fare più che parlare. Chi chiama per telefono non ha nulla di tutto questo.
Attiva Agente → Strumenti → Invia a chi chiama (send_to_caller nell'API degli agenti) e l'agente potrà mostrare fino a cinque schede alla volta sullo schermo di chi chiama: un titolo, una riga sotto, una descrizione, un'immagine, un link e fino a due pulsanti di risposta ciascuna; può anche proporre fino a tre risposte rapide sotto una domanda. I link non vengono mai letti ad alta voce.
L'agente può inviare solo link e immagini che gli sono stati dati in quella chiamata: le sue istruzioni e il saluto, la base di conoscenza (un documento letto da una pagina web porta il suo indirizzo), le risposte delle tue funzioni e le schede predefinite. Inoltre un link deve essere in uno degli allowed_hosts (il sito di una scheda predefinita lo è sempre). I link che l'agente inventa, o che chi chiama detta a voce, non vengono inviati. I link a quei siti nelle parole dell'agente sono cliccabili nella chat.
"send_to_caller": {
"enabled": true,
"allowed_hosts": ["shop.example.com", "*.cdn.example.com"],
"presets": [
{ "name": "hours", "when": "asked when we open", "title": "Opening hours",
"description": "Mon–Sat 9:00–18:00", "url": "https://shop.example.com/stores", "image_url": "" }
]
}
Ogni invio ti arriva come webhook call.message_sent (channel, items con title e url, quickReplies, blocked). Una chiamata invia al massimo 10 volte.
Durante la chiamata chi chiama può anche scrivere (un indirizzo e-mail, un numero d'ordine) o toccare un pulsante di risposta; l'agente risponde come al parlato, fermandosi prima se stava parlando. Fino a 500 caratteri per messaggio, uno al secondo, 100 per chiamata. Nel registro della chiamata questi turni sono contrassegnati come digitati o toccati.
I visitatori possono anche iniziare scrivendo invece di parlare: il widget e la pagina ospitata offrono entrambe le cose, o solo una se lo scegli in Agent → Deploy. Una conversazione scritta non ha voce e si paga a messaggio. Per chattare con un agente dal tuo server, usa la Chat API.
Il widget dà alla tua pagina un oggetto evasay. Tutto è facoltativo, e il frame della chiamata ascolta la tua pagina solo se è uno dei siti consentiti del widget (Agente → Distribuisci):
<script src="https://evasay.com/voice-widget.js" data-agent="AGENT_SLUG" async></script>
<script>
window.evasay = window.evasay || [];
evasay.push(function (agent) {
agent.setVariables({ plan: 'pro', page: location.pathname }); // for the next call
agent.update('Cart: 2 items, $120', { key: 'cart' }); // during it
agent.registerTool('add_to_cart', async function (args) {
// your code, in the visitor's browser
return { ok: true, checkout: 'https://shop.example.com/checkout' };
});
agent.on('cards', function (cards) {}); // also 'live', 'ended'
});
</script>
setVariables riempiono {{name}} nelle istruzioni e nel saluto. Provengono dal browser del visitatore, quindi all'agente viene detto che non sono verificati, e non arrivano mai alle tue funzioni né alla consultazione di avvio.update dice all'agente che cosa succede nella pagina senza farlo rispondere; un aggiornamento più recente con la stessa key sostituisce il precedente."kind": "page", senza url) e registra nella tua pagina una funzione con lo stesso nome. L'agente può chiamarla solo nelle chiamate da una pagina che l'ha registrata; aspetta la risposta fino a timeout_sec (1–10, predefinito 5) a meno che wait_for_result sia false. Viene eseguita con l'accesso del visitatore, come un suo clic: chiedi conferma nella tua pagina prima di qualsiasi cosa che costi denaro o non si possa annullare. I link nella sua risposta possono essere inviati come schede.Imposta Chi può avviare una chiamata su Solo con un token, e fai ottenere al tuo server un token monouso per l'utente connesso:
curl https://evasay.com/api/v1/voice/web-calls \
-X POST \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "AGENT_ID", "user_id": "u_42", "variables": { "name": "Ann" }, "expires_in": 600 }'
La risposta contiene token (una chiamata, entro expires_in secondi, 30–3600, predefinito 600), agent (lo slug) e web_call_url. Passa il token alla pagina con data-token-url="/your/endpoint" sullo script del widget (fa un POST lì con i cookie del visitatore e legge { "token": "…" }) oppure con agent.setToken(async () => token). Le variables del token sono verificate: le istruzioni, la consultazione di avvio e i modelli delle tue funzioni possono usarle, come user_id, che la chiamata conserva (userId nella chiamata, user_id per filtrare le chiamate). Tieni la tua chiave API sul tuo server.
Nella tua app, fai POST di { "token": "…", "pageTools": ["add_to_cart"] } a https://evasay.com + web_call_url. La risposta è la connessione della chiamata (un indirizzo di offerta WebRTC, o un indirizzo WebSocket, con il suo token di chiamata), per un client RTVI come l'SDK client di Pipecat; per iOS, Android e React Native vedi App mobili. Schede, funzioni di pagina e avvisi arrivano come server-message RTVI (evasay.cards, evasay.tool, evasay.notice); invia le parole digitate con send-text e le segnalazioni e risposte della pagina come client-message evasay.context e evasay.tool_result. Oppure trasporta tu l'audio con Audio tramite WebSocket, passando user_id e page_tools.