Trigger e azioni dei workflow HubSpot per WhatsApp

Flowella aggiunge trigger WhatsApp e cinque azioni ai workflow HubSpot. Usateli per inviare template e messaggi, attendere la risposta di un contatto o l’invio di un Flow, leggere documenti nelle proprietà del contatto e creare PDF. Questa pagina elenca ogni trigger e ogni azione con i relativi campi, output e codici di errore. Diverse azioni dipendono dalla finestra di 24 ore: per 24 ore dopo che un contatto ha scritto al vostro numero WhatsApp, potete inviargli qualsiasi messaggio. Fuori dalla finestra, WhatsApp consegna solo i template approvati.

Prima di iniziare

Collegate HubSpot a Flowella e verificate che Custom workflow actions sia sotto Unlocked nella scheda Capabilities in Settings → HubSpot. Vedere Funzionalità.
Per i trigger, deve essere sbloccato anche Contact activity events (message sent, read, replies, forms). Vedere Verificare che gli eventi di attività del contatto siano sbloccati.
Usate workflow basati sui contatti. Le azioni di Flowella funzionano solo sui contatti. I workflow HubSpot sono inclusi nei piani Professional ed Enterprise.
Per inviare template, abbiate almeno un template approvato. Vedere Template.
Memorizzate i numeri WhatsApp in formato internazionale, ad esempio +447700900123. Vedere Formato del numero di telefono.

Vedere Prima di iniziare per la checklist completa.

Le azioni di invio usano sempre il vostro numero WhatsApp predefinito. Per verificarlo o modificarlo, vedere Tabella dei numeri collegati.

Come funziona un invio da workflow

Questo diagramma mostra cosa succede quando un workflow invia un template e come la risposta del contatto torna in HubSpot. I passaggi relativi alla casella di posta HubSpot si applicano solo quando il canale personalizzato Flowella è collegato.

HubSpot trattiene il contatto in un passaggio di invio finché Flowella non comunica il risultato, per un massimo di un’ora. Flowella comunica il successo quando WhatsApp contrassegna il messaggio come inviato.
Se un invio fallisce, il passaggio fallisce con un motivo e un codice di errore, e il workflow prosegue con il passaggio successivo. Vedere Codici di errore.
Ogni invio appare nella casella di posta Flowella. I template inviati da un workflow appaiono anche nel thread della casella di posta HubSpot, come nome e lingua del template. I messaggi di Send WhatsApp Message e Send WhatsApp Reply non appaiono nel thread della casella di posta HubSpot.

Trigger

Quando scegliete un trigger per un workflow basato sui contatti, o l’evento per un passaggio Delay until event, cercate Flowella. HubSpot elenca gli eventi sotto Flowella: WhatsApp Forms Integration, ad esempio Flowella: WhatsApp Forms Integration: Form Completed.

Trigger	Si attiva quando	Proprietà dell’evento
Form Completed	Un contatto invia un WhatsApp Flow e Flowella invia le risposte al modulo HubSpot	`formName`, `source` (sempre `WhatsApp Flow`)
Text Reply	Un contatto invia un messaggio di testo, tocca un pulsante di risposta rapida, sceglie da un elenco o invia un Flow	`phone`, `message`, `responseTimeSeconds`
Message Sent	WhatsApp segnala che un messaggio di Flowella è stato inviato al contatto	`phone`, `deliveryStatus` (sempre `sent`), `templateName` (solo invii di template)
Message Read	WhatsApp segnala che il contatto ha letto un messaggio di Flowella	`phone`, `messageType`, `timeToReadSeconds`

Potete filtrare su queste proprietà nel trigger, nei passaggi Delay until event e negli elenchi attivi. Per il riferimento completo delle proprietà, vedere Proprietà degli eventi per il filtraggio.

Form Completed (in entrata)

Questo trigger si attiva quando un contatto invia un WhatsApp Flow.

Si attiva solo per gli invii di WhatsApp Flow. Un invio dello stesso modulo HubSpot dal sito web non lo attiva, quindi per quelli usate il trigger di invio modulo di HubSpot.
L’evento registra il nome del modulo e la sorgente, non le risposte. Flowella invia le risposte a HubSpot come invio del modulo da cui è stato creato il Flow. Create i rami in base alle proprietà del contatto scritte dal modulo.
Filtrate su Form Name in modo che solo gli invii di quel modulo iscrivano il contatto o terminino l’attesa.

Uso tipico: elaborare un modulo di prenotazione, di feedback o di onboarding non appena il contatto lo invia.

Text Reply (in entrata)

Questo trigger si attiva quando un contatto vi invia un messaggio di testo. Si attiva anche quando il contatto:

Tocca un pulsante di risposta rapida. La risposta è l’etichetta del pulsante.
Sceglie un’opzione da un elenco. La risposta è il titolo dell’opzione.
Invia un WhatsApp Flow. La risposta è un riepilogo di una riga che inizia con il titolo del Flow.

Non si attiva per immagini, messaggi vocali, video o documenti, anche quando hanno una didascalia. Poiché l’invio di un Flow conta come risposta, anche un passaggio Delay until event che attende Text Reply termina quando il contatto invia un Flow. Per instradare in base a ciò che il contatto ha scritto, iscrivete su Text Reply e create un ramo sulla proprietà del contatto Last WhatsApp reply message (flowella_last_reply_message). Flowella scrive la risposta in questa proprietà, e l’orario in Last WhatsApp reply at (flowella_last_reply_at), prima che l’evento si attivi. La proprietà contiene sempre la risposta che ha attivato il trigger. Usate corrispondenze esatte per scelte fisse come Yes e No. Vedere Proprietà del contatto sull’ultima risposta WhatsApp.

Non filtrate il trigger stesso sulla proprietà Message dell’evento. HubSpot verifica i filtri degli eventi su ogni evento Text Reply che il contatto abbia mai inviato, quindi un filtro per parola chiave corrisponde sia alle risposte vecchie sia a quella nuova. Ricostruite qualsiasi workflow che filtra su Text Reply → Message in modo che crei invece un ramo su Last WhatsApp reply message.

STOP, UNSUBSCRIBE, CANCEL, END e QUIT sono parole chiave di opt-out. Quando una di esse costituisce l’intero messaggio, Flowella registra l’opt-out del contatto dai messaggi di quel numero WhatsApp. Il messaggio attiva comunque Text Reply, quindi non create percorsi che chiedono ai contatti di rispondere con queste parole e non etichettate un pulsante di risposta rapida Cancel o Stop. Vedere Come funzionano gli opt-out tramite parola chiave.

Uso tipico: instradare i contatti in base a risposte come Yes, Book o Help, oppure inviare un Flow quando un contatto chiede qualcosa.

Message Read (in uscita)

Questo trigger si attiva quando WhatsApp segnala che il contatto ha letto un messaggio che avete inviato tramite Flowella. messageType è il tipo di messaggio letto: TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT, TEMPLATE, SYSTEM o OTHER. Filtrate su messageType uguale a TEMPLATE per considerare solo le letture dei template. Uso tipico: fare follow-up solo dopo che il contatto ha visto il vostro primo messaggio.

Message Sent (in uscita)

Questo trigger si attiva quando WhatsApp segnala che un messaggio di Flowella è stato inviato al contatto. Copre i messaggi dai workflow, dalla casella di posta Flowella e dagli invii di massa. deliveryStatus è sempre sent, perché Flowella non registra le consegne come eventi. templateName contiene il nome del template per gli invii di template, ad esempio flowella_form_reminder. Uso tipico: tracciare i messaggi che il vostro team invia dalla casella di posta Flowella, oppure avviare un timer di follow-up. Un workflow non ha bisogno di questo trigger per i propri invii, perché gli output del passaggio di invio li registrano già.

Usare “Delay until event” con i trigger Flowella

Il passaggio Delay until event di HubSpot mette in pausa un contatto finché non si verifica un evento Flowella, o finché non scade un limite di tempo. Poi un passaggio Branch verifica se l’evento si è verificato in tempo. Ad esempio, un workflow può:

Inviare un Flow con Send WhatsApp Template.
Attendere con Delay until event, impostato sull’evento Flowella Form Completed e filtrato su Form Name.
Creare un ramo in base al fatto che il contatto abbia inviato in tempo. In caso contrario, inviare un promemoria o creare un’attività.

Potete attendere qualsiasi evento Flowella:

Form Completed: attendete le risposte del Flow, poi create un ramo sulle proprietà scritte dal modulo.
Text Reply: attendete una risposta qualsiasi, poi create un ramo su Last WhatsApp reply message.
Message Read: attendete che il contatto apra il vostro messaggio, poi decidete se fare follow-up.

Pianificate il limite di tempo tenendo conto della finestra di 24 ore. Un follow-up in testo semplice raggiunge il contatto solo se vi ha scritto nelle ultime 24 ore. Dopo un’attesa più lunga, fate follow-up con Send WhatsApp Template o Send WhatsApp Reply.

Azioni

Flowella aggiunge cinque azioni ai workflow basati sui contatti. Cercate il nome dell’azione quando aggiungete un passaggio.

Azione	Cosa fa	Quando la finestra di 24 ore è chiusa
Send WhatsApp Template	Invia un template approvato, inclusi i template con un pulsante Flow	Invia normalmente
Send WhatsApp Message	Invia testo semplice	Fallisce
Send WhatsApp Reply	Invia testo, oppure lo racchiude nel template di risposta intelligente Service	Invia il template, oppure salta se lo scegliete
AI Document Reader	Legge un PDF o un’immagine e scrive i valori nelle proprietà del contatto	Non influisce
Generate Document	Crea un PDF da un modello di documento e lo salva nei file di HubSpot	Non influisce

Assign to Customer Agent è un’azione di HubSpot, non un’azione di Flowella. Vedere Affidare le conversazioni al Customer Agent di HubSpot.

Output delle azioni di invio

Send WhatsApp Template, Send WhatsApp Message e Send WhatsApp Reply restituiscono questi output. I passaggi successivi del workflow possono usarli come token di dati.

Output	Cosa contiene
Message ID	L’ID di WhatsApp per il messaggio.
Message status	`sent` quando il passaggio riesce, oppure `delivered` o `read` se WhatsApp lo ha segnalato prima. `failed` quando il passaggio fallisce.
Recipient WhatsApp ID	Il numero del contatto in formato internazionale, senza il `+`.
Message type	`template` o `text`.
Sent at	Quando il passaggio è terminato, come timestamp UTC.
Error message	Perché il passaggio è fallito. HubSpot mostra questo messaggio anche nella cronologia del workflow.
Error code	Un codice breve per l’errore. Vedere Codici di errore.

Send WhatsApp Template

Questa azione invia un template WhatsApp approvato al contatto iscritto dal vostro numero predefinito. I template con un pulsante Flow vengono inviati allo stesso modo, quindi è così che si invia un Flow da un workflow.

Campo	Descrizione
Contact Phone Number (obbligatorio)	La proprietà del contatto che contiene il numero WhatsApp del destinatario, in formato internazionale. Se la proprietà è vuota per un contatto, Flowella usa il numero di telefono WhatsApp del contatto (`hs_whatsapp_phone_number`), poi il numero di cellulare (`mobilephone`), poi il numero di telefono (`phone`).
Template Name (obbligatorio)	Il template da inviare. L’elenco mostra i template approvati del WhatsApp Business Account del vostro numero predefinito. Ogni nome appare con spazi e lettere maiuscole, quindi `booking_confirmation` appare come Booking Confirmation.
Contact Email	Facoltativo. Flowella non lo usa durante l’invio.
Template Variable 1 to 5	I valori per le variabili del template. Mappate proprietà HubSpot o altri token di dati. Una variabile di intestazione testuale occupa Template Variable 1, e le variabili del corpo seguono in ordine.

Variabili

Mappate le variabili nell’ordine in cui le mostra il template. Le intestazioni con immagine, video e documento non occupano uno slot. Ad esempio, un template ha {{1}} nell’intestazione e {{1}} e {{2}} nel corpo. Mappate Template Variable 1 sul valore dell’intestazione e Template Variable 2 e 3 sui valori del corpo.
Se un valore mappato è vuoto, o mappate meno slot di quante variabili abbia il template, Flowella invia il valore di riserva confermato del template. Se non esiste un valore di riserva confermato, l’invio fallisce. Vedere Valori di riserva.
L’azione ha cinque slot. Per ogni variabile dopo la quinta, Flowella invia il valore di riserva confermato, altrimenti l’invio fallisce.
Le date appaiono in UTC. Vedere Variabili di data e ora.
Per un’intestazione con posizione, mappate latitudine e longitudine negli slot successivi alle variabili del corpo. Vedere Intestazioni con posizione.

Media, pulsanti e lingua

Le intestazioni con immagine, video e documento usano sempre il media salvato con il template. Non potete cambiare il media per ogni contatto da HubSpot.
Non potete impostare i valori dei pulsanti per ogni contatto. Inserite invece link o codici specifici per contatto in una variabile del corpo.
Quando il template ha un pulsante Flow, Flowella passa al Flow l’ID HubSpot del contatto iscritto. Questo aiuta Flowella ad associare l’invio allo stesso contatto.
Se il template esiste in più lingue, Flowella invia la versione en. Se non esiste una versione en, invia quella aggiornata più di recente. Le versioni in en_GB o en_US non contano come en. Vedere Lingua.

Invii duplicati. Se lo stesso template, nella stessa lingua, va allo stesso numero di telefono dallo stesso numero WhatsApp entro 15 secondi, Flowella lo invia una sola volta. L’altro passaggio fallisce immediatamente con DUPLICATE_TEMPLATE_SEND_SUPPRESSED e il workflow prosegue. Di solito succede quando due contatti HubSpot condividono un numero di telefono e vengono iscritti nello stesso momento. Il template ha comunque raggiunto quel numero di telefono. Vedere Invio del template soppresso come duplicato.

Send WhatsApp Message

Questa azione invia un messaggio in testo semplice al contatto iscritto dal vostro numero predefinito. Non può inviare media, pulsanti o template.

Campo	Descrizione
Recipient Phone Number (obbligatorio)	La proprietà del contatto che contiene il numero WhatsApp del destinatario. Se è vuota per un contatto, Flowella usa il numero di telefono WhatsApp del contatto, poi il numero di cellulare, poi il numero di telefono.
Message Text (obbligatorio)	Il messaggio. Personalizzatelo con i token di dati HubSpot, come il nome del contatto.

Punti chiave:

Il messaggio raggiunge il contatto solo all’interno della finestra di 24 ore. Flowella non verifica prima la finestra. Se il contatto non ha scritto al vostro numero predefinito nelle ultime 24 ore, WhatsApp rifiuta il messaggio (errore Meta 131047) e il passaggio fallisce. Vedere Errore 131047.
Quando la finestra potrebbe essere chiusa, usate invece Send WhatsApp Reply o Send WhatsApp Template.
Flowella invia il testo esattamente come lo compila HubSpot. Non riformatta le date.
Il messaggio appare nella casella di posta Flowella, non nel thread della casella di posta HubSpot.

Send WhatsApp Reply

Questa azione invia il vostro messaggio come testo normale quando la finestra di 24 ore è aperta. Quando la finestra è chiusa, invia il messaggio all’interno del vostro template di risposta intelligente Service, così può comunque raggiungere il contatto. Usatela quando un workflow può essere eseguito ore o giorni dopo l’ultimo messaggio del contatto.

Campo	Descrizione
Message body (obbligatorio)	Il vostro messaggio. Personalizzatelo con i token di dati HubSpot.
Skip if window is closed	Se selezionata, l’azione non invia un template. Se la finestra è chiusa, il passaggio fallisce con `SESSION_CLOSED_SKIPPED` e il workflow prosegue.

L’azione non ha un campo telefono. Flowella usa il numero di telefono WhatsApp del contatto, poi il numero di cellulare, poi il numero di telefono. Questo diagramma di flusso mostra come l’azione decide cosa inviare. Quando la finestra è chiusa:

Flowella usa sempre il template di risposta intelligente Service. Compila {{1}} con il nome del contatto, {{2}} con il nome della vostra organizzazione e {{3}} con il vostro messaggio.
I template di risposta intelligente sono solo in inglese.
Se il template Service è disattivato, non ancora approvato o messo in pausa da Meta, il passaggio fallisce con il messaggio “Smart Reply template is not approved yet. Check Settings → Reply Templates.” Controllate il template in Settings → WhatsApp (Meta) → Smart replies. Vedere Risposte intelligenti.

Meta può addebitare il messaggio sia che la finestra sia aperta sia che sia chiusa. Vedere Prezzi e categorie di messaggi. Come Send WhatsApp Message, questa azione invia il testo come lo compila HubSpot, e i suoi messaggi non appaiono nel thread della casella di posta HubSpot. Quando usarla al posto di Send WhatsApp Message:

Follow-up di riattivazione e di customer success che possono essere eseguiti dopo 24 ore di silenzio.
Follow-up dopo un’attesa di Form Completed con un limite di tempo lungo.
Qualsiasi invio che deve raggiungere il contatto a prescindere dallo stato della finestra.

Tracciare la finestra in una proprietà HubSpot

Flowella può mantenere aggiornata una proprietà del contatto con l’orario in cui si chiude la finestra di 24 ore del contatto. Flowella scrive in whatsapp_window_open_until ma non la crea, quindi createla prima in HubSpot:

In HubSpot, create una proprietà del contatto. Consultate la guida di HubSpot sulla creazione di proprietà.
Scegliete il tipo di campo Date and time picker.
Verificate che il nome interno sia esattamente whatsapp_window_open_until prima di salvare. HubSpot non consente di modificare un nome interno in seguito.

Ogni volta che il contatto vi invia un messaggio, Flowella imposta la proprietà a 24 ore dopo quel messaggio. Ciò richiede che CRM contacts (auto-create on new WhatsApp chat) sia sotto Unlocked in Settings → HubSpot. Usate la proprietà in rami ed elenchi, ad esempio per trattare in modo diverso i contatti la cui finestra si è chiusa. La proprietà riflette l’ultimo messaggio del contatto a uno qualsiasi dei vostri numeri WhatsApp. Send WhatsApp Reply verifica la finestra solo sul vostro numero predefinito.

AI Document Reader

Questa azione legge un PDF o un’immagine, trova i valori richiesti e li scrive nelle proprietà del contatto iscritto. Usatela per i documenti che i vostri contatti vi inviano, come un file caricato tramite un modulo HubSpot o un WhatsApp Flow.

Campo	Descrizione
Document source (obbligatorio)	Dove si trova il documento. Inserite un link `https://`, l’ID numerico di un file nei file di HubSpot, oppure il nome interno di una proprietà del contatto che contiene un link o un ID file.
Field map JSON (obbligatorio)	Un array JSON di massimo 40 voci. Ogni voce associa un valore da trovare (`extract`) al nome interno della proprietà del contatto in cui scriverlo (`hubspot`).
Extraction instructions	Suggerimenti facoltativi, ad esempio dove compare un valore nel documento. Flowella usa i primi 2.000 caratteri.
Clear HubSpot properties when empty	Se selezionata, un valore che Flowella non trova svuota la proprietà corrispondente. Se non selezionata, Flowella lascia invariata quella proprietà.

Una mappa dei campi si presenta così:

[
  { "extract": "passport_number", "hubspot": "passport_number" },
  { "extract": "date_of_birth", "hubspot": "date_of_birth" },
  { "extract": "full_name", "hubspot": "firstname" }
]

Ogni nome extract inizia con una lettera, usa solo lettere, numeri e trattini bassi, ed è lungo al massimo 64 caratteri. Usate ogni nome extract una sola volta. Documenti che Flowella può leggere:

File PDF, JPEG, PNG e WebP, fino a 15 MB. Flowella controlla il contenuto del file, non il nome. Altri formati, incluse le foto HEIC degli iPhone, falliscono con DOCUMENT_UNSUPPORTED_TYPE.
PDF fino a 4 pagine.
I link devono iniziare con https://.

Se un PDF contiene poco o nessun testo, come una scansione, Flowella lo legge visivamente, allo stesso modo di una foto. Come vengono scritte le proprietà:

Flowella scrive tutti i valori in un unico aggiornamento del contatto.
Se una qualsiasi proprietà nella mappa dei campi non esiste in HubSpot, o HubSpot rifiuta un valore, l’intero aggiornamento fallisce con HUBSPOT_PATCH_FAILED. Nessuna proprietà cambia. Controllate ogni nome interno prima di attivare il workflow.
Clear HubSpot properties when empty determina cosa succede alle proprietà per i valori che Flowella non trova. I valori trovati vengono sempre scritti.

Quando il passaggio riesce, restituisce questi output:

Output	Cosa contiene
Properties written	I nomi interni delle proprietà scritte da Flowella, separati da virgole.
Page count	Il numero di pagine lette da Flowella.
Extraction mode	`text` per i PDF con testo leggibile, oppure `vision` per immagini e PDF scansionati.

Codici di errore:

Codice di errore	Significato
`DOCUMENT_SOURCE_MISSING`	Document source è vuoto, oppure la proprietà del contatto indicata non contiene alcun link o ID file.
`DOCUMENT_SOURCE_NOT_HTTPS`	Il link non inizia con `https://`.
`DOCUMENT_DOWNLOAD_FAILED`	Flowella non è riuscito a scaricare il file.
`DOCUMENT_TOO_LARGE`	Il file supera i 15 MB.
`DOCUMENT_UNSUPPORTED_TYPE`	Il file non è un PDF, JPEG, PNG o WebP.
`DOCUMENT_TOO_MANY_PAGES`	Il PDF ha più di 4 pagine.
`DOCUMENT_EXTRACT_FAILED`	Flowella non è riuscito a leggere il documento.
`HUBSPOT_PATCH_FAILED`	HubSpot ha rifiutato l’aggiornamento, ad esempio perché una proprietà nella mappa dei campi non esiste. Non è stato scritto nulla.
`FIELD_MAP_MISSING`, `FIELD_MAP_EMPTY`, `FIELD_MAP_INVALID_JSON`, `FIELD_MAP_INVALID`, `FIELD_MAP_DUPLICATE`, `FIELD_MAP_TOO_LARGE`	Field map JSON manca, è vuoto o non è JSON valido, contiene una voce che viola le regole sopra, ripete un nome `extract` oppure ha più di 40 voci.
`HUBSPOT_NOT_CONNECTED`	Flowella non riesce a raggiungere il vostro account HubSpot. Ricollegate HubSpot.

Generate Document

Questa azione compila un modello di documento Flowella con le proprietà HubSpot del contatto iscritto, crea un PDF e lo salva nei vostri file di HubSpot, nella cartella flowella-documents. Create i modelli nella schermata Modelli di documento in Flowella.

Campo	Descrizione
Document template ID (obbligatorio)	L’ID del modello. Copiatelo con Copy ID in Settings → Document templates.
Output filename	Facoltativo. Il nome del file PDF. Se lo lasciate vuoto, Flowella assegna al file il nome del modello. I caratteri diversi da lettere, numeri, punti, trattini e trattini bassi diventano trattini bassi, e Flowella aggiunge `.pdf`.
HubSpot file property	Facoltativo. Il nome interno di una proprietà del contatto in cui Flowella salva l’ID file HubSpot del nuovo file. La proprietà deve già esistere.

Quando il passaggio riesce, restituisce questi output:

Output	Cosa contiene
File URL	Un link temporaneo di Flowella al PDF. Smette di funzionare un’ora dopo la fine del passaggio. Non salvatelo in una proprietà e non inseritelo in un’e-mail.
HubSpot file ID	L’ID del PDF nei file di HubSpot. Usatelo per trovare il file in seguito.

Flowella salva i PDF generati nei file di HubSpot come file pubblici. Chiunque abbia il link di un file può aprirlo, e i motori di ricerca possono indicizzarlo. Non inserite dati personali sensibili, come numeri di documenti d’identità o dati sanitari o finanziari, nei modelli di documento. I file che i contatti caricano in un WhatsApp Flow vengono salvati nei file di HubSpot allo stesso modo.

Codici di errore:

Codice di errore	Significato
`DOCUMENT_TEMPLATE_ID_INVALID`	Document template ID non è un ID modello valido.
`DOCUMENT_TEMPLATE_NOT_FOUND`	Nella vostra organizzazione non esiste alcun modello con quell’ID. Potrebbe essere stato eliminato.
`DOCUMENT_TOKEN_MISSING`	Una proprietà usata nel modello è vuota per questo contatto.
`DOCUMENT_TEMPLATE_INVALID`, `DOCUMENT_TEMPLATE_TOO_LARGE`	Il JSON del modello non è valido, oppure è troppo grande.
`DOCUMENT_RENDER_FAILED`	Flowella non è riuscito a creare il PDF.
`HUBSPOT_FILE_UPLOAD_FAILED`	HubSpot non ha accettato il file.
`HUBSPOT_PATCH_FAILED`	Flowella ha salvato il file ma non è riuscito a scriverne l’ID in HubSpot file property, ad esempio perché la proprietà non esiste.
`HUBSPOT_NOT_CONNECTED`	Flowella non riesce a raggiungere il vostro account HubSpot. Ricollegate HubSpot.

Codici di errore

Quando Send WhatsApp Template, Send WhatsApp Message o Send WhatsApp Reply falliscono, la cronologia del workflow del contatto mostra il motivo e l’output Error code contiene un codice breve. Il workflow prosegue poi con il passaggio successivo.

Codice di errore	Azioni	Cosa significa	Cosa fare
`CONTACT_PHONE_MISSING`	Tutte e tre	Il contatto non ha alcun numero nella proprietà mappata né nelle proprietà telefoniche su cui Flowella ripiega.	Aggiungete il numero WhatsApp del contatto in formato internazionale.
`CONTACT_PHONE_INVALID`	Tutte e tre	Il numero non è un numero internazionale valido, ad esempio un numero locale come `07700 900123`.	Memorizzatelo come `+447700900123`. Vedere Formato del numero di telefono.
`CONTACT_OPTED_OUT`	Tutte e tre	Il contatto ha revocato il consenso ai messaggi dal vostro numero predefinito.	Non scrivete al contatto. Vedere Opt-out.
`TEMPLATE_NOT_FOUND`	Template	Flowella non trova un template approvato con questo nome per il vostro numero predefinito. Potrebbe essere stato eliminato, rinominato o non ancora approvato.	Scegliete di nuovo il template in Template Name.
`TEMPLATE_WABA_MISMATCH`	Template	Il template appartiene a un WhatsApp Business Account diverso da quello del vostro numero predefinito.	Scegliete un template dall’account del numero predefinito.
`VARIABLE_EMPTY_NO_FALLBACK`	Template	Una variabile è vuota e il template non ha un valore di riserva per essa. Il messaggio di errore indica la variabile.	Mappate una proprietà che abbia un valore, oppure aggiungete e confermate un valore di riserva. Vedere Valori di riserva.
`DUPLICATE_TEMPLATE_SEND_SUPPRESSED`	Template	Lo stesso template è stato inviato allo stesso numero di telefono negli ultimi 15 secondi.	Nulla. Il numero di telefono ha ricevuto il template una volta.
`MESSAGE_TEXT_MISSING`	Message	Message Text è vuoto dopo che HubSpot ha compilato i token di dati.	Controllate il testo e le proprietà usate dai suoi token.
`MESSAGE_BODY_MISSING`	Reply	Message body è vuoto dopo che HubSpot ha compilato i token di dati.	Controllate il testo e le proprietà usate dai suoi token.
`SESSION_CLOSED_SKIPPED`	Reply	La finestra è chiusa e Skip if window is closed è selezionata.	Nulla, se volevate saltare. Altrimenti deselezionate la casella.
`CHANNEL_NOT_FOUND`	Message, Reply	La vostra organizzazione non ha alcun numero WhatsApp collegato.	Collegate un numero in Settings → WhatsApp (Meta).
`HUBSPOT_CONTACT_NOT_FOUND`	Message, Reply	HubSpot non ha trovato il contatto, ad esempio perché è stato eliminato.	Controllate il contatto in HubSpot.
`HUBSPOT_NOT_CONNECTED`, `META_NOT_ENABLED`, `META_NOT_CONNECTED`	Message, Reply	Flowella non riesce a raggiungere il vostro account HubSpot, oppure WhatsApp non è collegato.	Ricollegate HubSpot in Settings → HubSpot, oppure WhatsApp in Settings → WhatsApp (Meta).
Inizia con `FLOWELLA_META:`	Tutte e tre	WhatsApp ha rifiutato il messaggio, oppure ha segnalato in seguito che non è riuscito. La parte dopo i due punti indica il motivo.	Vedere la tabella successiva.
`FAILED`	Tutte e tre	Qualsiasi altro errore. Il messaggio di errore indica la causa.	Leggete il messaggio di errore.

Quando il codice è FAILED, il messaggio di errore fornisce più dettagli. Ad esempio:

Per Send WhatsApp Template, i problemi di configurazione mostrano il codice sottostante tra parentesi: “Flowella could not send this WhatsApp template (CHANNEL_NOT_FOUND). Check the workflow action inputs, then try again.”
Per Send WhatsApp Reply, un template Service non disponibile mostra “Smart Reply template is not approved yet. Check Settings → Reply Templates.”
Quando una variabile è vuota e il suo valore di riserva non è ancora stato confermato, il messaggio indica che il valore di riserva non è stato verificato. Confermate i valori di riserva nel template. Vedere Template con valori di riserva non verificati.
Per Send WhatsApp Message e Send WhatsApp Reply, quando WhatsApp rifiuta subito il messaggio, il messaggio riporta il motivo di WhatsApp.

Codici che iniziano con FLOWELLA_META:

Codice di errore	Errore Meta	Cosa significa
`FLOWELLA_META:re_engagement_required`	131047	La finestra di 24 ore si è chiusa. Vedere Errore 131047.
`FLOWELLA_META:message_undeliverable`	131026	WhatsApp non è riuscito a consegnare il messaggio. Il numero potrebbe non usare WhatsApp.
`FLOWELLA_META:sender_quality_block`	131048	WhatsApp ha bloccato l’invio a causa di segnali di qualità o di spam sul vostro numero. Vedere Errore 131048.
`FLOWELLA_META:marketing_limit`	131049	WhatsApp ha limitato i messaggi di marketing verso questo contatto. Vedere Coinvolgimento sano dell’ecosistema.
`FLOWELLA_META:marketing_opt_out`	131050	Il contatto ha bloccato i messaggi di marketing della vostra azienda in WhatsApp. Vedere Errore 131050.
`FLOWELLA_META:marketing_disabled`	131063	Gli invii di template Marketing sono disattivati per la vostra configurazione WhatsApp in Meta.
`FLOWELLA_META:template_classification_limit`	131064	WhatsApp ha limitato l’invio a causa di problemi con la categoria del template.
`FLOWELLA_META:pacing_held_dropped`	132015	WhatsApp ha trattenuto il messaggio mentre verificava i primi feedback sul template, poi lo ha scartato perché il feedback era negativo.
`FLOWELLA_META:template_parameters`	132000, 132012	I valori inviati non corrispondono alle variabili, all’intestazione o ai pulsanti del template.
`FLOWELLA_META:phone_not_registered`	133010	Il vostro numero WhatsApp non è completamente registrato presso Meta.
`FLOWELLA_META:rate_limited`	Limite di frequenza	Meta ha limitato la velocità di invio. Riprovate più tardi.
`FLOWELLA_META:service_unavailable`	Errore temporaneo	WhatsApp ha avuto un problema temporaneo. Inviate di nuovo più tardi.
`FLOWELLA_META:generic`	Altro	WhatsApp ha rifiutato il messaggio. Il messaggio di errore include il motivo di WhatsApp.

Per le soluzioni per ogni codice e per altri errori WhatsApp, vedere Codici di errore WhatsApp in Flowella. Per problemi di connessione e sincronizzazione, vedere Errori di sincronizzazione HubSpot.

Affidare le conversazioni al Customer Agent di HubSpot

Assign to Customer Agent è un’azione dei workflow di HubSpot, non fa parte di Flowella. Affida una conversazione al Customer Agent, l’agente IA di HubSpot per la casella di posta delle conversazioni. L’agente può rispondere su WhatsApp solo quando il canale personalizzato Flowella è collegato. Le risposte dell’agente seguono le stesse regole di qualsiasi risposta dalla casella di posta HubSpot:

Testo semplice dal numero predefinito. Gli allegati vengono scartati.
Solo all’interno della finestra di 24 ore. Se il contatto non ha scritto al vostro numero predefinito nelle ultime 24 ore, la risposta non viene consegnata. Flowella pubblica i chip Re-engage nel thread, e una persona deve fare clic su uno di essi per inviare un template.
Solo messaggi testuali. L’agente vede messaggi di testo, tocchi sui pulsanti, scelte da elenco e riepiloghi dei Flow. Non vede immagini, messaggi vocali, video o documenti.
Nessun indicatore di digitazione. Al momento Flowella non mostra al contatto un indicatore di digitazione prima delle risposte dell’agente.
Gli opt-out si applicano. I contatti che hanno revocato il consenso non ricevono le risposte dell’agente.

Assegnate l’agente mentre la finestra è aperta, ad esempio subito dopo un trigger Text Reply. Un workflow che attende 48 ore prima di assegnare l’agente spesso lo lascia nell’impossibilità di rispondere. Vedere Usare il Customer Agent di HubSpot con Flowella.

Schemi di workflow

Questi schemi combinano i trigger e le azioni di Flowella con i passaggi di HubSpot. Per ricette complete passo dopo passo, vedere Ricette di workflow HubSpot.

Schema 1: inviare un Flow e attendere le risposte

Inviare il Flow

Aggiungete Send WhatsApp Template e scegliete un template con un pulsante Flow.

Attendere l'invio

Aggiungete Delay until event, impostato su Form Completed e filtrato su Form Name. Impostate un limite di tempo.

Creare un ramo in base all'esito

Aggiungete un Branch in base al fatto che l’evento si sia verificato in tempo.

Elaborare le risposte

Se il contatto ha inviato, create un ramo sulle proprietà del contatto scritte dal modulo, poi aggiornate i record o create attività.

Fare follow-up

Se il contatto non ha inviato, inviate un promemoria con Send WhatsApp Template o Send WhatsApp Reply, oppure create un’attività per il vostro team.

Schema 2: instradare in base alla risposta del contatto

Impostare il trigger

Iscrivete i contatti su Text Reply.

Creare un ramo in base alla risposta

Create un ramo su Last WhatsApp reply message, ad esempio uguale a Book o Change booking.

Inviare il Flow giusto

Per Book, aggiungete Send WhatsApp Template con il template del vostro Flow di prenotazione.

Attendere le risposte

Aggiungete Delay until event, impostato su Form Completed e filtrato su Form Name, poi create un ramo in base al risultato.

Schema 3: feedback con follow-up

Inviare il modulo di feedback

Aggiungete Send WhatsApp Template con il template del vostro Flow di feedback.

Attendere la risposta

Aggiungete Delay until event, impostato su Form Completed e filtrato su Form Name.

Creare un ramo in base al punteggio

Create un ramo sulla proprietà del punteggio scritta dal modulo:

Punteggio alto: ringraziate il contatto con Send WhatsApp Message. L’invio del Flow ha aperto una nuova finestra di 24 ore.
Punteggio basso: create un’attività per il vostro team, oppure usate Assign to Customer Agent mentre la finestra è aperta.

Schema 4: affidare le risposte al Customer Agent

Impostare il trigger

Iscrivete i contatti su Text Reply.

Confermare la ricezione del messaggio

Facoltativamente, aggiungete Send WhatsApp Message per confermare di aver ricevuto il messaggio del contatto.

Assegnare l'agente

Aggiungete l’azione di HubSpot Assign to Customer Agent. Il contatto vi ha scritto un momento fa, quindi l’agente può rispondere all’interno della finestra di 24 ore.

Variabili di data e ora

Quando mappate una proprietà HubSpot di data o data e ora su una Template Variable in Send WhatsApp Template, Flowella la mostra come dd.MM.yyyy HH:mm in UTC. Ad esempio, 27.06.2026 14:30.

Flowella usa sempre UTC, non il fuso orario del contatto. Durante l’ora legale britannica, un appuntamento alle 14:30 appare come 13:30.
Una proprietà di sola data mostra 00:00 come orario.
Flowella tratta qualsiasi numero separato di 13 cifre in una variabile del template come un timestamp. Un numero d’ordine o di riferimento di 13 cifre può apparire come una data.
Send WhatsApp Message e Send WhatsApp Reply non riformattano le date. Inviano il testo come lo compila HubSpot.

Per mostrare l’ora locale o un altro formato, memorizzate la data come testo in una proprietà HubSpot, ad esempio Tuesday 4 November, 14:30, e mappate invece quella proprietà. Vedere Date da HubSpot.

Suggerimenti e buone pratiche

Usate numeri di telefono internazionali. Memorizzate i numeri WhatsApp con + e il prefisso internazionale, ad esempio +447700900123. Un numero locale come 07700 900123 fallisce con CONTACT_PHONE_INVALID.

Date nomi chiari ai template. L’elenco Template Name mostra i nomi con spazi e lettere maiuscole. booking_confirmation_restaurant si legge come Booking Confirmation Restaurant, che è più facile da trovare di template_1.

Inviate, poi attendete. Abbinate ogni invio a un passaggio Delay until event, in modo che il workflow gestisca sia i contatti che rispondono sia quelli che non rispondono.

Fate prima un test con un piccolo gruppo. Iscrivete un contatto di prova con il vostro numero prima di attivare un workflow per tutti. Controllate le variabili, il formato del numero di telefono e ogni ramo.

Correlati

Attività del contatto

Gli eventi Flowella su ogni contatto e le proprietà su cui potete filtrare.

Canale personalizzato

Portate le conversazioni WhatsApp nella casella di posta HubSpot.

Variabili dei template

Esempi, valori di riserva e come i valori HubSpot compilano un template.

Risposte intelligenti

I template Service, Update e Offer usati fuori dalla finestra di 24 ore.

Ricette di workflow

Workflow HubSpot passo dopo passo creati con queste azioni.

Tracciamento UTM e delle inserzioni

Scoprite quale inserzione, link o codice QR ha avviato ogni conversazione.

​Prima di iniziare

​Come funziona un invio da workflow

​Trigger

​Form Completed (in entrata)

​Text Reply (in entrata)

​Message Read (in uscita)

​Message Sent (in uscita)

​Usare “Delay until event” con i trigger Flowella

​Azioni

​Output delle azioni di invio

​Send WhatsApp Template

​Send WhatsApp Message

​Send WhatsApp Reply

​Tracciare la finestra in una proprietà HubSpot

​AI Document Reader

​Generate Document

​Codici di errore

​Affidare le conversazioni al Customer Agent di HubSpot

​Schemi di workflow

​Schema 1: inviare un Flow e attendere le risposte

​Schema 2: instradare in base alla risposta del contatto

​Schema 3: feedback con follow-up

​Schema 4: affidare le risposte al Customer Agent

​Variabili di data e ora

​Suggerimenti e buone pratiche

​Correlati

Attività del contatto

Canale personalizzato

Variabili dei template

Risposte intelligenti

Ricette di workflow

Tracciamento UTM e delle inserzioni

Prima di iniziare

Come funziona un invio da workflow

Trigger

Form Completed (in entrata)

Text Reply (in entrata)

Message Read (in uscita)

Message Sent (in uscita)

Usare “Delay until event” con i trigger Flowella

Azioni

Output delle azioni di invio

Send WhatsApp Template

Send WhatsApp Message

Send WhatsApp Reply

Tracciare la finestra in una proprietà HubSpot

AI Document Reader

Generate Document

Codici di errore

Affidare le conversazioni al Customer Agent di HubSpot

Schemi di workflow

Schema 1: inviare un Flow e attendere le risposte

Schema 2: instradare in base alla risposta del contatto

Schema 3: feedback con follow-up

Schema 4: affidare le risposte al Customer Agent

Variabili di data e ora

Suggerimenti e buone pratiche

Correlati