Il numero su cui vive il voice agent (backend) e quello che vede l’ospite (frontend) sono spiegati in Telefonia e 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.
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
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.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.
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:- la prenotazione è attiva: mai a prenotazioni cancellate, no-show o già concluse;
- siamo dentro il soggiorno: dalle 14:30 del giorno di arrivo alle 10:00 del giorno di partenza, ora italiana;
- il check-in online è completato.
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 comescope_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:
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.- Prima si provano gli strumenti chiamando direttamente il gateway: ricerca prenotazione, rifiuti delle istruzioni d’accesso,
scope_id. Costo zero. - 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.
- 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 loscope_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.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:La Variable del token, passo per passo
Il codice canonico dei tool di prenotazione legge il token dello studente dalla VariableMATTONE_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.
1
Apri il workspace dello studente
In Conduit, con un utente amministratore del workspace dello studente: Impostazioni → Variabili (Settings → Variables).
2
Crea la Variable
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.3
Se lo studente ha il tool dei pagamenti
Stessa cosa con
MATTONE_STRIPE_TOKEN e il token della sua integrazione Stripe (anche questo si legge dal codice del suo tool).4
Verifica
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 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.
Come si applica a uno studente
1
Copia di sicurezza
Prima di cambiare qualcosa, salva le istruzioni attuali del voice agent (le personalizzazioni dello studente non devono andare perse).
2
Regola zero
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.
3
Impostazioni fisse
Controlla lingua specifica, contesto del contatto attivo ed escalation verso il referente dello studente.
4
Blocco in cima
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.
5
Quattro chiamate di prova
Vedi sotto. Solo dopo le quattro prove il lavoro è finito.
Verifica: quattro chiamate di prova
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 dice dove guardare.