Riferimento dei blocchi | Guida di Userbot

Una scheda per blocco, da consultare mentre configuri. Se stai ancora decidendo quale blocco usare, parti da I blocchi disponibili.

Per ogni blocco trovi i parametri che accetta, il riferimento con cui lo richiami nelle espressioni e cosa espone a valle sotto output. Il riferimento è quello che ottiene il primo blocco di quel tipo nella tela; dal secondo in poi si aggiunge un numero, come agent2 o condition3. → La sintassi dei riferimenti

Tutti i campi di testo accettano riferimenti fra doppie parentesi graffe, da soli o dentro una frase. In cima alle impostazioni di ogni blocco c’è una breve descrizione con un Esempio.

Trigger

Riferimento: trigger. Il tipo si sceglie fra le schede in cima al pannello.

Tipo	Parametri
Manuale	Nessuno. Il pannello spiega da dove si avvia
Integrazione	Connessioni collegate ed Evento trigger
Webhook	Indirizzi Produzione e Test, generati da soli; liste di Sicurezza

Espone a valle: l’input dell’esecuzione, che si richiama con $input. Con Integrazione, l’output del Trigger contiene anche i dati dell’evento. → Come si avvia un workflow

Agente

Riferimento: agent.

Parametro	Cosa ci scrivi	Default
Agente	Quale agente esegue il passaggio, fra quelli a cui hai accesso	Quello che hai scelto nel pannello
Prompt	La richiesta da fargli. Obbligatorio	Il testo del messaggio dell’utente
Allegati	I file da passargli	Gli allegati del messaggio dell’utente

Espone a valle: i messaggi prodotti dall’agente.

Dentro un workflow l’agente lavora con le sue istruzioni, la sua conoscenza e le azioni delle sue integrazioni, ma non riceve le sue Mini App né i suoi workflow, e non può fare domande né inviare email dalla chat.

Se l’agente non è più condiviso con te, il blocco segnala che non è disponibile e va sostituito.

Invia messaggio

Riferimento: sendMessage.

Parametro	Cosa ci scrivi	Default
Messaggio	Una o più parti di testo, aggiunte con + Aggiungi messaggio. Grassetto, corsivo, sottolineato, elenchi, link, emoji e GIF	Una parte vuota
Pulsanti	Per ciascuno Etichetta, Azione (Continua il flusso oppure Apri link) e, per i link, URL	Nessun pulsante

Le parti arrivano in chat come un unico messaggio. Ogni pulsante Continua il flusso diventa un’uscita sulla tela e mette il flusso in attesa della scelta; i pulsanti Apri link non fermano niente.

Espone a valle: se il messaggio è stato emesso e quale pulsante è stato premuto.

Con pulsanti di proseguimento serve una conversazione: fuori da una chat il passaggio fallisce.

Richiesta dati

Riferimento: requestData.

Parametro	Cosa ci scrivi	Default
Messaggio in chat	Il testo che accompagna il modulo	Compila i campi per continuare.
Campi	L’elenco dei campi del modulo	Un campo
Modello estrazione AI	Il modello che prova a compilare i campi dalla conversazione. Serve solo se usi l’Estrazione AI	Nessuno

Ogni campo ha Etichetta, Tipo e Obbligatorio. Sotto Avanzate trovi Nome in output (il nome con cui il valore esce dal blocco: con un punto, come dati.email, raggruppi più campi) e Suggerimento nel modulo. Con Estrazione AI attiva, e una Descrizione per l’AI, il campo si compila da solo se il valore è già nella conversazione; non vale per File e Password.

Tipo di campo	Cosa accetta	Impostazioni proprie
Testo Corto	Una riga	Lunghezza max
Testo Lungo	Più righe	Lunghezza max
Calendario	Una data	Data min, Data max
Numero	Un valore numerico	Min, Max, Step
Email	Un indirizzo email
Password	Testo mascherato
Lista di opzioni	Una scelta fra quelle che elenchi	Opzioni
File	Un allegato	Tipi accettati, Consenti più file, Dimensione max (MB)

Espone a valle: un valore per campo, sotto il suo Nome in output.

Serve una conversazione: senza, il passaggio fallisce.

QR Code

Riferimento: qrCode.

Parametro	Cosa ci scrivi	Default
Contenuto	L’indirizzo o il testo da codificare. Obbligatorio	Vuoto

Espone a valle: l’immagine prodotta, 280 per 280 pixel. Compare in chat solo se l’esecuzione ha una conversazione.

Scala ad umano

Riferimento: scalaSuOperatore. Compare solo se il Customer Service è attivo nella vostra area di lavoro.

Parametro	Cosa ci scrivi	Default
Timeout	Quanto aspettare, da 1 secondo a 24 ore	30 secondi
Torna all’Agente AI se scade il timeout	Sì o no	Sì
Nota per l’operatore (opzionale)	Il contesto per chi prende in carico. Non la vede l’utente	Vuoto

Non ancora attivo: Timeout e Torna all’Agente AI se scade il timeout non hanno effetto. Il flusso resta in attesa finché un operatore non prende in carico la conversazione.

Serve una conversazione: senza, il passaggio fallisce.

Nota

Riferimento: stickyNote. Un commento sulla tela, con testo formattato. Non ha ingressi né uscite e non gira mai.

Condizione

Riferimento: condition.

Parametro	Cosa ci scrivi	Default
Condizioni	Un elenco di rami. Ognuno ha un’Etichetta e una modalità: Prompt AI, con la regola scritta a parole, oppure Manuale, con un’espressione	Un ramo, Condition 1, in modalità Prompt AI
Consenti condizioni multiple	Se attivo, proseguono tutti i rami veri, in ordine. Se spento, vince il primo	Spento
Forza l’AI a scegliere un percorso	Se attivo, i rami Prompt AI ne scelgono comunque uno, anche senza corrispondenza perfetta	Spento
Modello e Memoria (scheda Contesto)	Il modello che valuta i rami Prompt AI e quanta conversazione legge	Nessuna memoria
In caso di errore	Vedi Se un blocco fallisce	Interrompi workflow

Accanto a Condizioni, Prompt AI genera i rami da una descrizione: scrivi «VIP, urgente, tutto il resto» e scegli se Sostituisci condizioni o Aggiungi in fondo.

Un ramo Manuale si scrive fra doppie graffe, con confronti e operatori logici: {{hTTPRequest.output.status === 200}}, {{requestData.output.paese === "IT" && requestData.output.importo > 1000}}. Sono ammessi ==, ===, !=, !==, >, <, >=, <=, &&, ||, ! e i metodi includes, startsWith, endsWith.

Ogni ramo diventa un’uscita sulla tela. Se nessun ramo è vero, il flusso si ferma lì senza errori.

Espone a valle: il ramo o i rami scelti.

Pausa

Riferimento: pause.

Parametro	Valori ammessi	Default
Durata	Da 1 secondo a 24 ore, in minuti e secondi, oppure con le Durate rapide	30 secondi

Espone a valle: i dati che ha ricevuto, invariati.

Chiama workflow

Riferimento: callWorkflow.

Parametro	Cosa ci scrivi	Default
Workflow	Quale workflow avviare, fra quelli attivi. Obbligatorio	Nessuno
Punto di ingresso	Il trigger del workflow chiamato, oppure un blocco preciso	Trigger (default)
Modalità	Da qui in poi oppure Solo questo nodo. Compare solo se hai scelto un blocco	Da qui in poi

Il workflow chiamato esegue la sua versione pubblicata. La catena scende fino a 5 livelli e i cicli vengono rifiutati; un workflow può richiamare se stesso, ma una volta sola. Se la chiamata fallisce, il flusso prosegue con l’errore registrato. → Come gira un’esecuzione

Espone a valle: il risultato del workflow chiamato.

Codice

Riferimento: code.

Parametro	Cosa ci scrivi	Default
Linguaggio	JavaScript o Python	JavaScript
Codice	Il programma. I dati in arrivo sono in `input`, e quello che restituisci diventa l’output	`return input`
In caso di errore	Come gli altri blocchi con Gestione errori	Interrompi workflow

Inserisci contesto aggiunge al codice i dati dei blocchi a monte. Test esegue il codice nell’editor e mostra Output e Log: JavaScript gira nel browser, con un limite di 8 secondi; Python sui server di Userbot, con un limite di 25 secondi.

Non ancora attivo: durante un’esecuzione il codice non viene eseguito e il blocco lascia passare i dati invariati. In caso di errore non ha effetto.

HTTP request

Riferimento: hTTPRequest. Ha due schede, Configurazione e Test chiamata.

Parametro	Valori ammessi	Default
URL	L’indirizzo da chiamare. Obbligatorio. Se manca, `https://` viene aggiunto da solo	Vuoto
Metodo	GET, POST, PUT, PATCH, DELETE, HEAD	GET
Header	Coppie chiave/valore	Nessuna
Parametri di query	Coppie chiave/valore	Nessuno
Body	Nessuno oppure JSON, composto campo per campo. Le chiavi con il punto creano oggetti annidati. Non compare con GET e HEAD	Nessuno
In caso di errore	Interrompi workflow, Continua (con output di errore), Aggiungi callback di errore	Interrompi workflow

Espone a valle: status, headers e body della risposta.

Con Test chiamata fai partire la richiesta dall’editor e vedi Headers e Body della risposta. Da lì, Mappa body nel Contesto e Mappa header nel Contesto ti fanno scegliere un valore e pubblicarlo sotto un nome tuo, così a valle scrivi hTTPRequest.output.userId invece di ripetere tutto il percorso. Le mappature si scelgono solo dopo un test.

Timeout 30 secondi, al massimo 5 reindirizzamenti, risposta troncata a 256 KB. Gli indirizzi della rete interna non sono raggiungibili. → Come gira un’esecuzione

Invia email

Riferimento: sendEmail. Compare solo se nell’area di lavoro è collegata una casella Gmail o Outlook.

Parametro	Cosa ci scrivi	Default
Destinatari	Uno o più indirizzi, separati da virgola. Obbligatorio	Vuoto
Rispondi a	Dove arrivano le risposte, se diverso dal mittente	Vuoto
Oggetto	Obbligatorio	Vuoto
Corpo	Il testo del messaggio	Vuoto

L’email parte dalla casella personale di chi ha avviato il flusso; se non ne ha una, dalla casella condivisa collegata più di recente. Se l’invio non riesce, il passaggio fallisce.

Espone a valle: l’esito dell’invio. Timeout 30 secondi.

Ricerca knowledge

Riferimento: knowledgeSearch.

Parametro	Cosa ci scrivi	Default
Dove cercare	Tutte, Una knowledge base oppure Più knowledge base, da scegliere con Aggiungi knowledge base o file	Tutte
File di questo nodo	File caricati solo per questo blocco con Carica file, fino a 25 MB. Non compaiono nella Libreria	Nessuno
Query di input	Cosa cercare. Se è vuota, si cerca l’ultimo messaggio dell’utente	Vuota
Come cercare	Ibrida, Per significato, Per parole esatte	Ibrida
Top K	Quanti risultati al massimo, da 1 a 20	10
Somiglianza minima	Sotto questa soglia un brano non conta, da 0 a 100%	0%
Modello e Memoria (scheda Contesto)	Il modello del blocco e quanta conversazione legge	Nessuna memoria

Tre uscite: Documenti trovati, Nessun documento trovato, Errore. Timeout 90 secondi.

Espone a valle: i brani trovati, il testo degli estratti e le fonti.

AI Core

Riferimento: aiCore. Ha due schede, Impostazioni e Contesto.

Parametro	Cosa ci scrivi	Default
Modello	Il modello da usare	Il modello predefinito
Prompt	Le istruzioni per il modello. Schermo intero apre un editor più grande	Vuoto
Parametri modello	Coppie Chiave/Valore da passare al modello	Nessuno
Tools	Con Aggiungi: un’azione di un’Integrazione, oppure Altri nodi della tela (HTTP request, Ricerca knowledge, Invia email, Codice, QR Code, azioni delle integrazioni). Per ognuno scrivi Nome e Descrizione, che dicono al modello quando usarlo	Nessuno
Input (scheda Contesto)	Ultimo messaggio utente oppure Fisso, con un testo tuo	Ultimo messaggio utente
Memoria (scheda Contesto)	Nessuno, Ultimi N messaggi (da 1 a 20) oppure Conversazione	Nessuno
In caso di errore	Come gli altri blocchi con Gestione errori	Interrompi workflow

Il modello può usare gli strumenti al massimo 10 volte per esecuzione. Timeout 180 secondi in tutto, 90 per ogni strumento.

Espone a valle: il testo prodotto, il modello usato e le chiamate agli strumenti.

Ricerca web

Riferimento: webSearch.

Parametro	Cosa ci scrivi	Default
Query	Cosa cercare. Obbligatoria	Vuota
URL ammessi	Siti a cui limitare la ricerca, con i loro sottodomini	Tutti i siti
Blacklist	Siti da escludere: in modalità Manuale un’espressione regolare per riga, in modalità Prompt una descrizione a parole	Nessuna
Modello e Memoria (scheda Contesto)	Il modello del blocco e quanta conversazione legge	Nessuna memoria

Restituisce fino a 5 risultati. Tre uscite: Risultati trovati, Nessun risultato, Errore. Timeout 45 secondi.

Espone a valle: la query usata e i risultati, con le fonti.

Azioni delle integrazioni

Riferimento: integrationTool. Un blocco per ogni azione, dalla categoria Integrazioni.

Parametro	Cosa ci scrivi	Default
Connessione	Su quale account gira l’azione. Le integrazioni create nell’area di lavoro hanno l’autenticazione già impostata e non la chiedono	Da scegliere
Parametri dell’azione	Per ognuno: Manual, con un valore tuo; Auto, compilato dal modello in base al contesto; Prompt AI, compilato dal modello seguendo una tua indicazione	Dipende dall’azione
Modello	Il modello che compila i parametri Auto e Prompt AI. Compare solo se ce n’è almeno uno	Il modello predefinito
In caso di errore	Come gli altri blocchi con Gestione errori	Interrompi workflow

Con una connessione personale l’azione gira sempre su quell’account, anche quando il flusso lo avvia qualcun altro. Timeout 90 secondi.

Espone a valle: i parametri usati e il risultato dell’azione.