> 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. # I blocchi disponibili Un workflow è una catena di blocchi. Ognuno riceve i dati da chi lo precede, fa una cosa sola e passa il risultato a chi segue. Questa pagina serve a orientarti: cosa fa ciascun blocco e quando sceglierlo. I parametri esatti, i valori ammessi e cosa ogni blocco espone a valle stanno nel [Riferimento dei blocchi](/riferimento-blocchi). ## Come è organizzato il pannello **Aggiungi nodi** ha tre categorie. La ricerca in cima cerca nella categoria aperta. | Categoria | Cosa contiene | | ---------------- | ----------------------------------------------------------------------------------------------------- | | **Agenti** | Un blocco per ciascun agente a cui hai accesso, più **Crea nuovo agente** | | **Nodi** | Il **Trigger** e i blocchi di Userbot, divisi nelle sezioni **Base**, **Flusso** e **AI e knowledge** | | **Integrazioni** | Le azioni delle app collegate e delle integrazioni create nell'area di lavoro, un blocco per azione | ![Il pannello Aggiungi nodi, aperto sulla categoria Nodi: la ricerca in cima, i pulsanti Agenti, Nodi e Integrazioni, e i blocchi raggruppati in Base, Flusso e AI e knowledge. Trigger è spento perché sulla tela ce n'è già uno](/_fern-img/eeafdd5a5a24718fe7e52a6af61a26e72a763d2ee57a06331d83c396ae182fcc.webp) Due blocchi compaiono solo a certe condizioni: **Invia email** se nell'area di lavoro c'è una casella Gmail o Outlook collegata, **Scala ad umano** se è attivo il Customer Service. ## Base #### Invia messaggio Scrive un messaggio nella conversazione, con testo formattato, emoji, GIF e, se vuoi, dei pulsanti. Ogni pulsante può **Continua il flusso** lungo un percorso proprio oppure **Apri link**. Senza pulsanti di proseguimento il flusso tira dritto; con almeno uno si ferma e aspetta la scelta. Le parti del messaggio arrivano in chat come un messaggio solo. I pulsanti di proseguimento hanno bisogno di una conversazione: se il flusso è partito da un webhook o da un evento, il passaggio fallisce. #### Richiesta dati Ferma il flusso e chiede dei dati in chat con un modulo vero: testo corto, testo lungo, calendario, numero, email, password, lista di opzioni, file. Con **Estrazione AI** il campo si compila da solo, se l'informazione è già nella conversazione; altrimenti lo compila la persona. Usalo quando l'informazione ce l'ha solo un umano e la vuoi in campi separati, non in una frase da interpretare. Funziona solo dentro una conversazione: senza, il passaggio fallisce. #### QR Code Genera un codice QR da un testo o un indirizzo e lo mostra in chat come immagine. Tipico nei flussi che preparano materiali per un evento o una spedizione. #### Scala ad umano Passa la conversazione al Customer Service e mette il flusso in attesa finché un operatore non la prende in carico. Mettilo dove il passaggio successivo ha conseguenze verso l'esterno: una risposta a un cliente, una decisione economica, una modifica non reversibile. **Non ancora attivo:** **Timeout** e **Torna all'Agente AI se scade il timeout** si impostano ma non hanno effetto. Il flusso resta in attesa finché un operatore non interviene, anche fuori orario. Se la conversazione è già passata a un operatore, il passaggio fallisce. #### Nota Un commento sulla tela per chi legge il flusso. Non si collega e non gira mai. ## Flusso #### Condizione Divide il percorso: un ramo per ogni caso. Ogni ramo è in modalità **Prompt AI**, con la regola scritta a parole e valutata da un modello, oppure **Manuale**, con un confronto preciso sui dati, per esempio `{{hTTPRequest.output.status === 200}}`. I rami si controllano in ordine e vince il primo vero. Con **Consenti condizioni multiple** proseguono tutti i rami veri. Con **Forza l'AI a scegliere un percorso** i rami Prompt AI ne scelgono comunque uno, anche senza una corrispondenza perfetta. Non esiste un ramo «altrimenti»: se nessun ramo è vero, il flusso si ferma lì senza errori. Se ti serve un'uscita di riserva, aggiungi un ultimo ramo che la descriva. #### Pausa Mette il flusso in attesa per una durata che decidi tu, da un secondo a 24 ore: dà tempo a un sistema esterno di finire prima che tu gli chieda il risultato. #### Chiama workflow Avvia un altro workflow, attivo e pubblicato, e ne attende l'esito. Puoi entrare dal suo trigger oppure da un blocco preciso, solo quello o da lì in poi. È il modo di riusare una procedura invece di ricopiarla: si corregge in un punto solo. La catena può scendere fino a 5 livelli e i cicli vengono rifiutati. → [Come gira un'esecuzione](/esecuzione-workflow) #### Codice Una trasformazione che i blocchi pronti non coprono, scritta in JavaScript o Python: riordinare un elenco, calcolare un valore, ripulire del testo. Con **Test** la provi nell'editor e vedi risultato e log. **Non ancora attivo:** il test funziona, ma durante un'esecuzione il codice non viene eseguito e il blocco lascia passare i dati invariati. Anche usato come strumento di **AI Core** non fa nulla. #### HTTP request Parla con i sistemi che non hanno un'integrazione dedicata: metodo, indirizzo, header, parametri di query e corpo della richiesta. Con **Test chiamata** fai la chiamata dall'editor, guardi la risposta e scegli quali campi portare a valle. #### Invia email Manda un'email con destinatari, indirizzo di risposta, oggetto e corpo, composti anche dai dati dei blocchi precedenti. Parte dalla casella Gmail o Outlook personale di chi ha avviato il flusso; se non c'è, dalla casella condivisa collegata più di recente. > **Warning** > > Scrivi i destinatari come valore fisso. È la protezione più semplice > contro un contenuto malevolo dentro un documento che dirotta una > comunicazione verso l'esterno. ## AI e knowledge #### Ricerca knowledge Cerca nelle basi di conoscenza della Libreria, o in file caricati solo per questo blocco, e restituisce i brani più pertinenti. Serve per dare ai blocchi successivi materiale affidabile su cui basarsi. Ha tre uscite: **Documenti trovati**, **Nessun documento trovato** ed **Errore**. Collegale tutte e tre, così il flusso sa cosa fare anche quando non trova niente. #### AI Core Chiede a un modello di scrivere, riassumere o riscrivere un testo con i dati del flusso. Gli puoi dare degli strumenti (azioni delle integrazioni, oppure altri blocchi della tela come **HTTP request** o **Ricerca knowledge**) e il modello decide da solo quando usarli. È la scelta giusta quando ti serve un testo pronto, senza costruire un agente apposta. #### Ricerca web Cerca su internet e restituisce i risultati con le fonti. Puoi limitare la ricerca ad alcuni siti, o escluderne altri. Serve quando al flusso mancano informazioni che nei vostri sistemi non ci sono: un prezzo di mercato, una notizia, i dati pubblici di un'azienda. Ha tre uscite: **Risultati trovati**, **Nessun risultato** ed **Errore**. ## Agenti e integrazioni **Agente** porta il ragionamento dentro il flusso: riceve i dati a monte, decide cosa fare e usa gli strumenti che gli hai collegato. Usalo dove il passaggio non si descrive con una regola fissa: capire di cosa parla una richiesta, scegliere fra opzioni, scrivere un testo su misura. Dove la regola è fissa, un blocco dedicato è più veloce, più prevedibile e non consuma. Dentro un workflow l'agente usa istruzioni, conoscenza e azioni delle integrazioni, ma non le sue Mini App né i suoi workflow. > **Note** > > Se il risultato dell'agente lo legge il blocco dopo, chiedigli un formato > strutturato: un testo libero è comodo per una persona, ma una condizione non ci > si orienta. I blocchi della categoria **Integrazioni** eseguono una singola azione su un'app collegata: creare un ticket, pubblicare un messaggio su un canale, aggiornare una riga. Scegli la **Connessione** e compila i parametri: ognuno si scrive a mano (**Manual**), si lascia compilare al modello (**Auto**) oppure si descrive con un **Prompt AI**. Con una connessione personale l'azione gira sempre su quell'account, anche quando il flusso lo avvia un collega. → [Connessioni personali e condivise](/connessioni) ## Se un blocco fallisce Un blocco che fallisce ferma il suo ramo: i blocchi a valle non girano e non c'è un ritentativo automatico. L'esecuzione risulta **fallita** solo se nessun ramo arriva in fondo; se un altro ramo finisce bene, l'esecuzione risulta completata anche se una parte si è fermata. Per questo, dopo una prova, guarda i singoli passaggi e non solo l'esito. Alcuni blocchi hanno una sezione **Gestione errori**, con la voce **In caso di errore**. Ha effetto su **HTTP request**, **Condizione**, **AI Core** e sui blocchi delle integrazioni. | Scelta | Cosa fa | Dove ha senso | | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | **Interrompi workflow** | Il passaggio fallisce | È il valore iniziale, e va bene quando il blocco produce il dato principale | | **Continua (con output di errore)** | Prosegue passando il messaggio di errore come risultato normale | Chiamate accessorie, di cui il resto del flusso può fare a meno | | **Aggiungi callback di errore** | Il blocco ottiene le uscite **Successo** ed **Errore**, e devia sulla seconda quando qualcosa va storto | Sistemi instabili, dove serve un percorso di recupero | Sulla **Condizione** la callback aggiunge l'uscita **Condizione non soddisfatta**, che scatta quando la valutazione stessa va in errore, non quando nessun ramo è vero. Gli altri blocchi seguono regole proprie: * **Ricerca knowledge** e **Ricerca web** non falliscono: in caso di problemi escono da **Errore**. Se quell'uscita non è collegata, il ramo si chiude in silenzio. * **Agente** e **Chiama workflow** proseguono sull'uscita normale, con l'errore registrato nel passaggio. * **Codice** mostra la sezione, ma durante un'esecuzione non ha effetto. Un blocco che prosegue in silenzio dopo un errore è la causa più comune di workflow che sembrano funzionare e non fanno nulla: se lo imposti su **Continua**, metti subito dopo un passaggio che se ne accorga.