> ## Documentation Index > Fetch the complete documentation index at: https://docs.mattone.co/llms.txt > Use this file to discover all available pages before exploring further. # Voice agent: il setup canonico > Come si configura il voice agent di ogni studente perché trovi la prenotazione e l'appartamento anche quando al telefono i nomi e i codici arrivano storpiati. Uguale per tutti, da applicare una volta e verificare con quattro chiamate. Il voice agent risponde al telefono agli ospiti dello studente. Al telefono il problema non è l'intelligenza dell'agente: è la **trascrizione**. I nomi delle case si somigliano e vengono pronunciati male o in un'altra lingua, e nei codici lettere e numeri si confondono (B/8, S/5, O/0, I/1). Basta un carattere sbagliato e la prenotazione «non si trova». Questa pagina è la configurazione standard: si applica a ogni studente con voice agent, nuovo o esistente, così lo stesso problema non si risolve a mano ogni volta. Il blocco qui sotto usa gli strumenti dell'MCP Gateway (check-availability, get-reservation-status), che oggi lavorano con **KrossBooking**. Prima di applicarlo, controlla che il workspace dello studente abbia questi custom tool: se non li ha, vanno attivati dalla piattaforma collegando Kross. Per chi usa un altro PMS (Guesty, Hostaway) valgono le stesse regole (cerca per telefono, conferma la casa leggendola, non scegliere mai a caso), ma con gli strumenti del PMS: il blocco va adattato, non copiato. Il numero su cui vive il voice agent (backend) e quello che vede l'ospite (frontend) sono spiegati in [Telefonia e WABA](/integrazioni/conduit/telefonia-waba). Qui si parla solo di **come ragiona** il voice agent. ## Regola zero: mai copiare il voice agent di un altro Un voice agent **non si crea mai copiando** le istruzioni di Cosmica Italia, Cosmica Dubai o di un altro studente. Caso reale (ottobre 2026): il voice agent di uno studente si presentava agli ospiti come «Cosmica», con le città di Cosmica (Milano, Bologna, Napoli) e senza nessuno strumento per cercare le prenotazioni. Chi chiamava sentiva il nome di un'altra azienda. Le istruzioni si scrivono **da zero per lo studente**, partendo solo da questa pagina. Prima di salvare, ogni riga di questa lista deve essere vera: | Controllo | Come si verifica | | - | - | | Nome dell'azienda | nelle istruzioni e nel messaggio di benvenuto c'è **solo** il nome dello studente. Cerca nel testo «Cosmica», «Mattone» e i nomi di altri studenti: zero risultati | | Città e zone | solo quelle dove lo studente gestisce davvero case | | Contatti per l'escalation | solo i numeri del referente dello studente, mai numeri di Cosmica o del team Mattone | | Strumenti | il workspace ha i custom tool di prenotazione (check-availability, get-reservation-status). Senza strumenti il voice agent **non si attiva** | | Dati sensibili | **nessuna** password Wi-Fi, codice porta, codice cancello o dato di carta nelle istruzioni. Codici e istruzioni di accesso arrivano solo dagli strumenti, dopo la verifica dell'ospite: scritti nel testo restano vecchi quando cambiano e li legge chiunque apra il workspace | | Pagamenti | il voice agent non chiede mai dati della carta | Ultima prova prima di consegnare: chiama il numero e ascolta il benvenuto. Se senti un nome che non è quello dello studente, il lavoro non è finito. ## Le impostazioni fisse | Impostazione | Valore | Perché | | - | - | - | | Lingua | **specifica** (es. italiano), mai «Multilingual» | con Multilingual la trascrizione storpia i nomi e le prenotazioni non si trovano | | Contesto del contatto | **attivo** | è quello che dà all'agente il numero di chi chiama | | Direttiva disponibilità | in cima alle istruzioni | senza, l'agente legge il calendario nativo e risponde «occupato» quando è libero | | Escalation | statica, verso il numero del team dello studente | l'agente prova prima a risolvere; passa una persona su richiesta insistita o emergenza. Il numero sta qui, mai nel prompt | ## Il blocco da mettere in cima alle istruzioni Va incollato **all'inizio** delle istruzioni del voice agent, prima di tutto il resto. Il resto delle istruzioni (tono, regole della casa, personalizzazioni dello studente) non si tocca. ```text theme={null} IMPORTANTE — PRENOTAZIONI E APPARTAMENTI (priorità massima, vale su tutto quello che segue). - Disponibilità per date → strumento check-availability. Mai il calendario nativo, mai la memoria. - Per trovare la prenotazione passa PRIMA il numero di telefono da cui l'ospite sta chiamando (lo hai nei dati del contatto): lo strumento lo accetta così com'è, con o senza prefisso. Solo se non trova niente chiedi nome e cognome e la data di arrivo. Il codice di prenotazione è l'ultima strada: fattelo dire un carattere alla volta e rileggilo prima di cercare. - Per sapere in quale appartamento è l'ospite NON fargli pronunciare il nome della casa: trova la prenotazione e leggigli tu il nome dell'appartamento e le date per conferma. Se non la trovi, chiedi l'indirizzo (via e città) invece del nome. - Se lo strumento dice che ha capito un nome per approssimazione, o propone più case, leggi i nomi all'ospite e fatti dire quale. Non scegliere mai tu. - Non dare codici, parcheggio o Wi-Fi finché l'appartamento non è confermato. ``` Per un voice agent che parla prima in inglese, lo stesso blocco in inglese: ```text theme={null} IMPORTANT — RESERVATIONS AND APARTMENTS (top priority, overrides everything below). - Availability for dates → check-availability tool. Never the native calendar, never memory. - To find the reservation, FIRST pass the phone number the guest is calling from (it is in the contact data): the tool accepts it as is. Only if nothing comes back, ask for first and last name and arrival date. The booking code is the last resort: have it spelled one character at a time and read it back before searching. - To know which apartment the guest is in, do NOT make them say the name of the house: find the reservation and read the apartment name and dates back for confirmation. If you cannot find it, ask for the street address instead of the name. - If the tool says it understood a name approximately, or lists several houses, read the names to the guest and let them choose. Never pick one yourself. - Do not give codes, parking or Wi-Fi until the apartment is confirmed. ``` ## Il prompt canonico, generato dalla piattaforma Dall'ottobre 2026 il prompt del voice agent non si scrive più a mano: lo genera la piattaforma da un'unica fonte, cambiando per ogni studente solo il marchio, la descrizione dell'attività, gli strumenti disponibili e il numero del team. Il blocco qui sopra resta valido come parte di quel prompt. Tre regole che il prompt canonico rispetta sempre, e che valgono anche per qualunque aggiunta fatta a mano: * **Nessun dato d'accesso nel prompt.** Password Wi-Fi, codici di porte e cancelli, numeri di serrature non si scrivono mai nelle istruzioni: un prompt li dice a chiunque chiami, a qualunque ora, senza nessun controllo. Li danno solo gli strumenti, con le regole qui sotto. * **Nessun numero di telefono nel testo.** Il numero verso cui trasferire sta nelle impostazioni di escalation, non nelle istruzioni. * **Nessun nome di un'altra azienda.** Un prompt copiato da un altro workspace si presenta con il marchio sbagliato: è successo, ed è il primo controllo da fare. La piattaforma ha un controllo automatico che cerca questi tre problemi nei prompt dei voice agent. ## Istruzioni d'accesso: le regole stanno nel gateway Codici, istruzioni di check-in, link d'accesso e apertura porta escono dagli strumenti solo se valgono **tutte** queste condizioni: 1. la prenotazione è **attiva**: mai a prenotazioni cancellate, no-show o già concluse; 2. siamo **dentro il soggiorno**: dalle **14:30 del giorno di arrivo** alle **10:00 del giorno di partenza**, ora italiana; 3. il **check-in online** è completato. Se una condizione manca, lo strumento rifiuta e dice all'agente cosa rispondere (per esempio «le istruzioni di accesso sono disponibili dalle 14:30 del giorno di arrivo»). Le regole sono nel gateway, uguali per tutti gli studenti e per ogni canale (voce e chat): non dipendono da cosa c'è scritto nel prompt. La verifica dell'identità (cognome dell'intestatario, data di arrivo) resta compito dell'agente ed è nel prompt canonico. ## La ricerca nella Knowledge Base sull'appartamento giusto (scope\_id) In chiamata Conduit non sa in automatico di quale appartamento si parla: la ricerca nella Knowledge Base va **limitata** passando l'id del listing come `scope_id`. Quando lo strumento di ricerca prenotazione trova la prenotazione, restituisce quell'id (riga «Conduit listing\_id» nel testo e campo `scope_id` nei dati), e il prompt dice all'agente di passarlo in ogni ricerca che riguarda l'appartamento. Quale id è dipende da come i listing arrivano in Conduit: | Come arrivano i listing | Id del listing in Conduit | Da dove lo prende il gateway | | - | - | - | | dal canale Airbnb (studenti con collegamento Kross partner) | l'id dell'annuncio Airbnb | dal registro appartamenti della piattaforma, se l'appartamento è **abbinato alla sua tipologia Kross** | | dal connettore Kross nativo (chiave Kross propria) | l'id della **camera** Kross (non l'id della tipologia) | dalla prenotazione stessa | Per gli studenti partner, senza l'abbinamento appartamento ↔ tipologia Kross nel registro appartamenti lo `scope_id` non esce. L'abbinamento si fa in piattaforma ed è parte dell'onboarding. ## Trasferimenti verso numeri italiani ed emiratini I trasferimenti da un voice agent su numero americano verso cellulari italiani o degli Emirati falliscono spesso: gli operatori internazionali filtrano le chiamate in arrivo dagli Stati Uniti (controlli anti-frode e di autenticazione del chiamante). Quando l'operatore rifiuta prima del collegamento, Conduit non registra il motivo: nei dati della chiamata il trasferimento risulta fallito e basta. * **Direzione:** il voice agent si può attivare anche su numero italiano (+39). Per i nuovi studenti è la strada da preferire: niente inoltro verso un numero americano, niente trasferimento internazionale. Gli SMS da numeri non americani richiedono approvazioni a parte. * **Finché si resta sul numero americano:** il prompt deve prevedere il ripiego. Se il trasferimento non riesce, l'agente prende nota con tutti i dati, dice all'ospite che il team è stato avvisato e continua ad aiutarlo; non lo lascia in attesa. ## Prove senza bruciare crediti Una chiamata con il voice agent costa circa **8 crediti al minuto**. Un giro di prove fatto a caso costa centinaia di crediti. 1. **Prima** si provano gli strumenti chiamando direttamente il gateway: ricerca prenotazione, rifiuti delle istruzioni d'accesso, `scope_id`. Costo zero. 2. **Poi** le chiamate vocali: da **un solo numero dedicato**, con un budget fissato prima (per esempio 100 crediti, cioè circa 12 minuti in tutto), e contando i minuti dai dati delle chiamate. 3. Prima di cambiare un voice agent si salva la sua configurazione attuale: è il ritorno indietro. ## Un esempio che funziona: l'integrazione Kross nativa Il voice agent che funziona meglio fra quelli che seguiamo è su un workspace collegato a Kross con l'**integrazione nativa di Conduit**: trova le prenotazioni, verifica la disponibilità, apre il cancello da remoto e manda il link del check-in per messaggio. Il motivo non è il prompt: con l'integrazione nativa le prenotazioni e i listing sono oggetti di Conduit, quindi l'agente sa di quale appartamento si parla senza passaggi in più. Con il collegamento partner (listing dal canale Airbnb) quello stesso legame si costruisce con lo `scope_id` e l'abbinamento nel registro appartamenti. ## Chi fa cosa: le attività manuali Quasi tutto il voice agent e i suoi strumenti vengono dalla piattaforma. Restano alcune attività che **non si possono fare da programma**: questa tabella dice chi le fa. | Attività | Chi | Perché lui | Se manca | | - | - | - | - | | Abbinare ogni appartamento alla sua tipologia Kross nel registro appartamenti | **team Mattone**, in piattaforma | ha davanti sia i listing Conduit sia le tipologie Kross; lo studente conferma solo i casi dubbi (due case con nomi simili) | per gli studenti partner lo `scope_id` non esce e la ricerca nella Knowledge Base in chiamata non sa di quale appartamento si parla | | Impostare la Variable del token nel workspace Conduit (passi sotto) | **team Mattone**, con accesso da amministratore al workspace dello studente; se il team non ha quell'accesso, la imposta il team in una call con lo studente che condivide lo schermo | Conduit non permette di impostare le Variables da programma | i tool usano ancora il token scritto nel codice (funzionano), e il controllo settimanale segnala il workspace | | Inoltrare il numero che conoscono gli ospiti verso il numero del voice agent | **studente**, dal pannello del suo operatore telefonico; il team verifica | il numero è dello studente | gli ospiti chiamano e non risponde nessuno, o risponde la segreteria | | Numero italiano per il voice agent (direzione futura) | **team Mattone** fa la richiesta a Conduit, lo studente fornisce i documenti che servono | l'acquisto e la verifica del numero passano da Conduit | si resta sul numero americano con inoltro, e i trasferimenti verso cellulari italiani possono fallire | | Contatti per l'escalation | **studente** dà il numero, **team Mattone** lo imposta nelle impostazioni di escalation | il numero è del team dello studente | l'agente non può trasferire: prende nota e avvisa, ma l'ospite non parla con nessuno | | Prove del voice agent | **team Mattone** | servono un numero dedicato e un budget di crediti | — | ### Cosa chiediamo allo studente, e con quali parole Questa guida è per il team: allo studente non si manda il link. Quando serve qualcosa da lui, il team glielo chiede con un messaggio breve, una cosa per volta: | Serve | Messaggio del team allo studente | | - | - | | Inoltro del numero | «Dal pannello del tuo operatore telefonico imposta l'inoltro di tutte le chiamate del numero che dai agli ospiti verso questo numero: \[numero del voice agent]. Quando hai fatto, scrivici: facciamo noi una chiamata di prova.» | | Numero per i trasferimenti | «A quale numero vuoi che l'assistente passi le chiamate quando serve una persona? Meglio un numero che risponde sempre, anche di sera.» | | Abbinamenti dubbi | «Questi due appartamenti hanno nomi simili: ci confermi quale corrisponde a quale annuncio?» seguito dai due nomi. | | Documenti per il numero italiano | quelli che chiede Conduit, elencati uno per uno nel messaggio; mai «guarda la guida». | | Accesso al workspace Conduit | «Ci serve un accesso da amministratore al tuo spazio Conduit per sistemare l'assistente: puoi invitare \[email del team]?» | ### La Variable del token, passo per passo Il codice canonico dei tool di prenotazione legge il token dello studente dalla Variable **`MATTONE_KROSS_TOKEN`** (il tool dei link di pagamento dalla Variable **`MATTONE_STRIPE_TOKEN`**). Se la Variable non c'è, usa il token scritto nel codice: nessun tool si rompe. In Conduit, con un utente **amministratore** del workspace dello studente: **Impostazioni → Variabili** (Settings → Variables). Nome: `MATTONE_KROSS_TOKEN`, esattamente così (maiuscole e trattini bassi). Valore: il token dello studente, cioè lo stesso valore che oggi compare nel codice del tool alla riga del ripiego. Il token si copia dal codice del tool di **quello** studente, mai da un altro workspace. Stessa cosa con `MATTONE_STRIPE_TOKEN` e il token della sua integrazione Stripe (anche questo si legge dal codice del suo tool). Dalla chat di test del workspace, una ricerca di prenotazione deve rispondere come prima. Una Variable sbagliata fa rispondere il gateway con un errore di token: in quel caso si corregge o si cancella la Variable, e il tool torna a usare il ripiego. ## Booking.com ed Expedia non passano più il telefono dell'ospite Da inizio ottobre 2026 Booking.com, e con buona probabilità Expedia, non passano più il numero di telefono dell'ospite ai channel manager. Cosa cambia: * **Ricerca della prenotazione al telefono.** Per questi ospiti il numero da cui chiamano non è nella prenotazione: se la ricerca per numero non trova niente, l'agente passa **subito** a nome, cognome e data di arrivo, oppure al codice. Il prompt canonico lo prevede. * **Dove mandare link e istruzioni.** Niente SMS o WhatsApp a un numero che non abbiamo: istruzioni, link del portale e video vanno nella **chat della piattaforma su cui l'ospite ha prenotato**. * **Raccogliere il telefono.** Il telefono va chiesto nel portale di check-in, così le volte dopo l'ospite si trova anche dal numero. ## Diagnosi ricorrenti (ottobre 2026) | Cosa si vede | Causa | Cosa si fa | | - | - | - | | Il voice agent si presenta con il nome di un'altra azienda | prompt copiato da un altro workspace | prompt canonico dalla piattaforma (vedi «Regola zero») | | Password Wi-Fi o codici scritti nelle istruzioni | aggiunti a mano per supplire alla Knowledge Base | toglierli; i dati d'accesso li danno gli strumenti, nella finestra del soggiorno | | In chiamata l'agente «non trova» Wi-Fi o istruzioni che nella Knowledge Base ci sono | la ricerca in chiamata non è limitata all'appartamento (`scope_id` assente), o un problema lato Conduit sulla ricerca in chiamata | `scope_id` dallo strumento di ricerca prenotazione; segnalazione a Conduit con gli id delle chiamate | | Il trasferimento a una persona fallisce | filtro degli operatori sulle chiamate dagli Stati Uniti verso l'Italia o gli Emirati | ripiego nel prompt (prende nota e avvisa); numero italiano per il voice agent | | Il numero degli ospiti non riceve più chiamate dal voice agent | inoltro verso il numero del voice agent saltato o numero non più comunicato agli ospiti | verificare l'inoltro dal pannello dell'operatore | | Codici dati a una prenotazione cancellata o prima dell'arrivo | controllo di stato e date assente negli strumenti | chiuso nel gateway: ora rifiuta (vedi «Istruzioni d'accesso») | ## Cosa tollera lo strumento (nomi e parole particolari) Gli strumenti che cercano prenotazioni e case stanno nell'MCP Gateway, uguali per tutti. Oggi fanno così: * **Ospite**: si cerca per numero di telefono (conta se ha almeno 7 cifre, in qualunque formato), per nome e cognome (anche solo una parte, parola per parola), per e-mail o per codice (quello Kross «375/2026» o quello del canale). Gli accenti non contano: «Sansò» e «Sanso» sono lo stesso nome. * **Casa**: accenti, apostrofi e maiuscole non contano («Cà», «Ca'», «ca» sono uguali). Se il nome non combacia, lo strumento tollera piccoli errori di trascrizione parola per parola: nessuno sotto le 4 lettere, uno fino a 7 lettere, due da 8 in su («Casa Muzeo» trova Casa Museo, «Casa Gato» trova Casa Gatto). Le parole generiche come «casa», «villa», «appartamento» non decidono da sole. * **Sicurezza**: se due o più case sono ugualmente vicine a quello che si è capito, lo strumento **non ne sceglie una**: restituisce i nomi e l'agente li legge all'ospite. Quando ha capito un nome per approssimazione, lo dice, e l'agente lo fa confermare. Per i nomi che l'agente **pronuncia** male quando li legge all'ospite (nomi stranieri, sardi, francesi), si aggiunge la parola nel **dizionario di pronuncia** del voice agent. Il dizionario cambia come l'agente parla, non come capisce: per capire ci pensa la ricerca tollerante qui sopra. ## Come si applica a uno studente Prima di cambiare qualcosa, salva le istruzioni attuali del voice agent (le personalizzazioni dello studente non devono andare perse). Controlla la tabella «mai copiare il voice agent di un altro» qui sopra: nome, città, contatti, strumenti, nessun dato sensibile. Se anche una riga non è vera, si corregge prima di andare avanti. Controlla lingua specifica, contesto del contatto attivo ed escalation verso il referente dello studente. Incolla il blocco canonico all'inizio delle istruzioni. Se c'erano righe che chiedevano all'ospite il nome della casa o il codice come primo passo, toglile: il blocco le sostituisce. Vedi sotto. Solo dopo le quattro prove il lavoro è finito. ## Verifica: quattro chiamate di prova | Prova | Come | Risultato giusto | | - | - | - | | 1. Numero conosciuto | chiama da un numero registrato su una prenotazione attiva | l'agente trova la prenotazione senza chiedere codici e legge il nome della casa per conferma | | 2. Numero sconosciuto | chiama da un altro numero, dai nome e data di arrivo | trova la prenotazione dal nome | | 3. Nome storpiato | chiedi la disponibilità di una casa pronunciandone male il nome | l'agente conferma il nome giusto prima di rispondere | | 4. Nome ambiguo | chiedi la disponibilità dicendo solo «casa» | l'agente elenca le case e chiede quale, non ne sceglie una | Queste quattro prove si fanno **dopo** le verifiche a costo zero sul gateway e con il budget della sezione «Prove senza bruciare crediti». Se una prova fallisce, la tabella dei [problemi ricorrenti](/delivery/problemi-ricorrenti-conduit) dice dove guardare. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.