> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.userbot.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server. # Riferimento dei blocchi Una scheda per blocco, da consultare mentre configuri. Se stai ancora decidendo quale blocco usare, parti da [I blocchi disponibili](/blocchi). 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](/riferimenti-dati) 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](/avvio-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](/blocchi) | **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](/esecuzione-workflow) **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](/esecuzione-workflow) ## 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.