> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.
# HubSpot Workflow Triggers and Actions in Flowella
> Set up Flowella's HubSpot triggers and actions — Form Completed, Text Reply, Send WhatsApp Template, Send WhatsApp Message, and AI agent handoff.
Flowella integrates directly into HubSpot's workflow engine, giving you custom triggers that fire on WhatsApp events and actions that send messages or hand conversations to an AI agent. This guide covers every trigger, every action, and the most effective patterns for combining them.
## Before you start
Make sure you have:
* A Flowella account connected to your HubSpot portal
* At least one WhatsApp template created in the Flowella app (required for sending messages)
* Access to HubSpot's workflow tool. Contact-based workflows require a Professional or Enterprise plan
All phone number properties used in Flowella workflow actions must be stored in international E.164 format, starting with `+` followed by the country code and national number (for example, `+447700900123`). See [Phone Number Format](/hubspot/phone-number-format) for details.
***
## Triggers
When you create a new contact-based workflow in HubSpot, search for **Flowella** in the trigger selection panel to see all available triggers. These fire whenever a specific WhatsApp event occurs and enrol the associated contact into the workflow automatically.
| Trigger | Direction | Fires when | Typical use | Key filterable properties |
| ------------------ | --------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- |
| **Form Completed** | Inbound | A contact submits a WhatsApp Flow form sent via Flowella | Process structured responses after a feedback, booking, or KYC flow | Form Name, Source, hs\_email, Occurred at |
| **Text Reply** | Inbound | A contact sends a free-text reply in a Flowella-managed conversation | Route on keywords, capture opt-in, detect intent | Message |
| **Message Read** | Outbound | A contact opens a WhatsApp message you sent | Follow up only once the message has been seen | Phone |
| **Message Sent** | Outbound | A WhatsApp message is dispatched to a contact via Flowella | Log outbound activity, start a follow-up timer | Phone |
### Form Completed (inbound)
This trigger fires when a contact completes a WhatsApp Flow form sent via Flowella. It is the most commonly used trigger and forms the backbone of most Flowella automations.
You can refine this trigger with the following event properties:
* **Form Name**: filter by a specific form so only completions of that form trigger the workflow
* **hs\_email**: the contact's email address at the time of the event
* **Occurred at**: the date and time the form was completed
* **Source**: the source of the form submission
**Typical use:** trigger a follow-up workflow after a customer completes a feedback form, a booking confirmation, a KYC questionnaire, or any other structured data collection flow.
### Text Reply (inbound)
This trigger fires when a contact sends a free-text reply to a WhatsApp conversation managed by Flowella.
What makes this trigger particularly powerful is the ability to **filter on message content**. When configuring the trigger criteria, add a condition on the **Message** property using operators such as "contains any of" to match specific keywords or phrases. This lets you build workflows that respond differently depending on what a contact says.
**Typical use:** route contacts based on keyword responses. For example, if a contact replies "yes" to a confirmation message, enrol them in one workflow; if they reply "cancel" or "help", enrol them in another. You can also use this to capture opt-in consent, trigger escalation paths, or detect intent from unstructured replies.
### Message Read (outbound)
This trigger fires when a contact reads (opens) a WhatsApp message sent through Flowella. It is useful for tracking engagement and building conditional logic around message delivery.
**Typical use:** start a follow-up sequence only after confirming the contact has seen your initial message, or flag contacts who have not read a message within a certain timeframe.
### Message Sent (outbound)
This trigger fires when a WhatsApp message is successfully sent to a contact via Flowella. It confirms dispatch from the Flowella platform rather than receipt by the contact. It is most useful as a trigger for sends that originate outside a HubSpot workflow, such as a reply sent by an agent from the Flowella inbox or an automated Flow response, since a workflow already knows about messages it sent itself.
**Typical use:** log outbound messaging activity, update CRM properties to record that a message has been dispatched, or start a timer for follow-up actions.
### Using "Delay until event" with Flowella triggers
One of the most powerful features of combining Flowella with HubSpot is the **Delay until event occurs** action. This allows a workflow to pause and wait for any Flowella event before continuing.
For example, you can build a workflow that:
1. Sends a WhatsApp Flow form to a contact
2. Pauses using **Delay until event** set to the Flowella event (these appear in the picker as **Flowella: WhatsApp Forms Integration: Form Completed** and so on)
3. Branches based on whether the event criteria were met within your chosen time window
This creates a true request-and-response pattern inside your automation. If the event does not occur within the delay period, the workflow branches down an alternative path, such as sending a reminder or escalating to a team member.
You can use this pattern with any Flowella event:
* **Wait for Form Completed**: pause until the contact finishes a WhatsApp Flow, then process their answers
* **Wait for Text Reply**: pause until the contact responds, then branch on the message content
* **Wait for Message Read**: pause until the contact opens the message, then decide whether to follow up or wait longer
## Actions
In addition to triggers, Flowella provides four custom workflow actions. These appear in the action panel when you add a step to any HubSpot contact-based workflow.
### Send WhatsApp Template
This action sends a pre-approved WhatsApp template message to a contact. Templates are created and managed in the Flowella app and include both standard message templates and interactive WhatsApp Flow templates (forms).
| Field | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contact Phone Number**\*(required)\* | Select the HubSpot contact property that holds the recipient's WhatsApp phone number. Must be in international format (e.g. `+447700900000`). |
| **Template Name**\*(required)\* | Choose from a dropdown of templates created in the Flowella app. This includes both standard message templates and Flow templates (interactive forms). |
| **Contact Email** | Optionally map the contact's email address. Flowella can use this for matching, enrichment, and analytics. |
| **Template Variable 1 to 5** | Map HubSpot contact or company properties to the personalisation variables defined in your template. For example, if your template includes `{{1}}` for first name, map Template Variable 1 to the First Name property. |
**Key points:**
* Flow templates (interactive forms) are selected exactly the same way as standard message templates, and Flowella handles the conversion automatically.
* You can map up to five template variables using any HubSpot data token, including enrolled contact properties, company properties, and data from earlier workflow actions.
* If a required template variable is left unmapped, the send may fail for that contact.
* This action is ideal for booking confirmations, feedback requests, renewal reminders, appointment notifications, and any other structured or templated message.
### Send WhatsApp Message
This action sends a direct WhatsApp message to a contact. Unlike the template action, this lets you compose a message on the fly within the workflow and supports multiple media types.
| Field | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Message Type**\*(required)\* | Choose from: Text Message, Document, Image, Video, or Audio. |
| **Recipient Phone Number**\*(required)\* | Select the HubSpot contact property that holds the recipient's WhatsApp phone number. |
| **Message Text** | For text messages, enter the message content. Personalise it using any HubSpot data token by clicking the data token panel. Available tokens include enrolled contact properties, associated records, trigger and event data, and outputs from previous workflow actions. |
**Key points:**
* Text messages can be fully personalised with dynamic content such as the contact's first name, a deal amount, or a ticket reference number.
* Media messages (image, video, audio, document) let you send rich content directly through WhatsApp as part of an automated workflow.
* This action is particularly useful for follow-up messages that do not require a pre-approved template, such as personalised thank-you messages or contextual responses triggered by earlier workflow logic.
### Send WhatsApp Reply
This action sends a personal-feeling WhatsApp message that **works even when the 24-hour customer service window has closed**. Use it instead of **Send WhatsApp Message** when the workflow may run hours or days after the customer's last inbound message.
| Field | Description |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Recipient Phone Number**\*(required)\* | Select the HubSpot contact property that holds the recipient's WhatsApp phone number. Must be in international format (e.g. `+447700900000`). |
| **Message**\*(required)\* | The message body. Personalise it with HubSpot data tokens (contact, company, deal, ticket, or previous action outputs). |
| **Skip if window is closed** | When checked, the action does **nothing** if the 24-hour window has closed. Use this if you only want to nudge contacts still in an active conversation. |
**How it works:**
* **Inside the 24-hour window** — your message sends as a normal free-form WhatsApp text.
* **Outside the window** — Flowella wraps your message into the active [reopen template](/settings/reply-templates) (variable `{{3}}`). The contact's first name (`{{1}}`) and your business name (`{{2}}`) are filled automatically. A Utility template conversation is opened (typically \~\$0.045 per send, depending on country — see [Pricing and conversation categories](/account/pricing-and-conversation-categories)).
**When to use it instead of Send WhatsApp Message:**
* Re-engagement, retention, and customer-success cadences that may run after 24h of silence.
* Follow-ups to **Form Completed** triggers when the workflow includes long delays.
* Any send where you want one HubSpot action to "just work" regardless of window state.
**Tip:** branch on the `whatsapp_window_open_until` contact property (synced by Flowella on inbound) if you need different logic for open vs closed windows before this action runs.
### Assign to Customer Agent
This action assigns a conversation to a HubSpot Breeze Customer Agent, initiating an AI-powered conversation directly within the Flowella WhatsApp channel.
| Field | Description |
| --------------------------------- | -------------------------------------------------------------------------- |
| **Agent to assign**\*(required)\* | Select which Breeze Customer Agent should handle the conversation. |
| **Record to assign** | Choose the record type to assign, such as "Conversations: All associated". |
When you assign a conversation to a Breeze Customer Agent via this action, the AI agent begins responding to the contact directly in WhatsApp through the Flowella channel. This means your customers receive intelligent, contextual answers without leaving the WhatsApp conversation they are already in.
This action is particularly valuable for:
* **Post-form support**: after a customer submits an enquiry form, the AI agent can answer follow-up questions immediately
* **Out-of-hours handling**: route WhatsApp conversations to an AI agent when your team is unavailable
* **Triage and escalation**: let the AI agent handle initial questions and only escalate to a human when needed
* **Product and service enquiries**: provide instant answers from your knowledge base without requiring a live agent
***
## Workflow patterns
Here are four common patterns that combine Flowella triggers, delays, and actions effectively.
### Pattern 1: Send and wait
The core pattern for any form-based interaction.
Add a **Send WhatsApp Template** action with a Flow form template.
Add a **Delay until event** action: Flowella: Form Completed.
Add a **Branch** action: Whether or not the event criteria were met.
Add a **Branch** action: whether or not the event criteria were met.
If criteria met: process the form data, update CRM properties, and trigger next steps.
If criteria not met: send a reminder or escalate to a team member.
***
### Pattern 2: Keyword-based routing
Route contacts into the right workflow based on what they reply.
Use **Flowella: Text Reply** where the Message property contains keywords such as "book" or "reserve".
Add a **Send WhatsApp Template** action with your booking Flow template.
Add a **Delay until event** — Flowella: Form Completed — then branch and process responses.
Add a **Delay until event** set to Flowella: Form Completed, then branch and process responses.
***
### Pattern 3: Feedback with smart follow-up
Collect feedback and take different actions depending on the score.
Add a **Send WhatsApp Template** action with your feedback Flow template.
Add a **Delay until event** — Flowella: Form Completed.
Add a **Delay until event** set to Flowella: Form Completed.
Use an **If/then branch** based on the score property:
* High score → send a thank-you message with a review link
* Low score → create a ticket and assign to a Customer Agent for AI-assisted recovery
Use an **If/then branch** based on the score property:
* High score: send a thank-you message with a review link
* Low score: create a ticket and assign to a Customer Agent for AI-assisted recovery
***
### Pattern 4: Conversational AI handoff
Hand off inbound replies directly to an AI agent.
Use **Flowella: Text Reply** to catch any inbound message.
Add a **Send WhatsApp Message** action to confirm you've received their message.
Add an **Assign to Customer Agent** action. The Breeze Customer Agent then handles the conversation natively in WhatsApp.
***
## Date and time variables
HubSpot stores date and date-time properties as **epoch milliseconds**. When you map one of those properties into a Flowella template variable, Flowella renders the value as **`dd.MM.yyyy HH:mm`** in the recipient's timezone — for example, `27.06.2026 14:30`.
This applies in three places:
* **Send WhatsApp Template** — any `Template Variable n` mapped to a HubSpot date or date-time property.
* **Send WhatsApp Message** — the same formatting is applied to inline date tokens used in the message body.
* **Legacy `variable_*` token payloads** — older API integrations that send epoch values without explicit type metadata are detected and rendered identically.
Appointment-date tokens injected from external HubSpot apps (for example, scheduling tools that write a "next appointment" property) are now rendered with the same `dd.MM.yyyy HH:mm` pattern. If you previously saw raw epoch numbers in the delivered message, you don't need to do anything — it's fixed at the platform level.
If you need a different format, create a **HubSpot calculated property** that formats the date as text (for example, `27 June 2026 at 14:30`) and map that to the template variable instead. Flowella treats text properties literally.
## Tips and best practices
**Use international phone number format.** Always store WhatsApp phone numbers in E.164 format (e.g. `+44` for UK, `+1` for US). Flowella requires this to deliver messages successfully.
**Name your templates clearly.** When creating templates in the Flowella app, use descriptive names that are easy to identify in HubSpot's dropdown. "Booking Confirmation Restaurant" is clearer than "Template 1".
**Combine triggers with delays for reliability.** The "send then wait" pattern ensures your workflow handles both responsive and non-responsive contacts gracefully, rather than relying solely on triggers.
**Use the Text Reply trigger for conversational routing.** By filtering on message content, you can build lightweight conversational interfaces without a full chatbot. Simple keyword matching can route contacts to the right workflow with minimal friction.
**Test with small audiences first.** When building new workflows, start by enrolling a small test group before rolling out to your full contact list. This helps you catch issues with template variables, phone number formatting, or branching logic early.