# Billing and subscriptions
Source: https://knowledge.flowella.io/account/billing
Pick a plan, manage your subscription through Stripe, and understand what happens when a subscription is trialing, active, or lapsed.
![Flowella billing and subscription]()
Flowella billing is handled through Stripe. This page covers how to choose a plan, where to manage payment details, and what changes when your subscription is in different states.
For plan limits and what each tier includes, see [Plans and limits](/account/plans-and-limits).
## Who can manage billing
Only the **Owner** of an organisation can change plan or update payment details. Admins and Members see the billing page but cannot make changes.
## Choosing or changing a plan
Go to **Settings → Billing** in the app. The page always syncs with Stripe on load, so you see the canonical state, not a cached snapshot.
Compare the plan cards on the Billing page and click **Upgrade to Starter** or **Upgrade to Pro**. **Enterprise** shows a **Contact sales** button that opens [flowella.io/contact](https://flowella.io/contact) instead of starting a checkout.
Flowella opens Stripe Checkout with your **email and phone** (if set on your profile) prefilled. Enter your **card details** and a **billing address** — the address is required so Stripe can apply the correct automatic tax. Stripe handles card processing; Flowella never sees your card number.
After checkout, Stripe redirects you back to **Settings → Billing**. The page polls until the new subscription is reflected in the app, usually within a few seconds. If checkout is cancelled, your existing plan is unchanged.
### Plan cards on the Billing page
The Billing page shows the plan cards side by side. Prices come from Stripe, so what you see on the card is what Stripe Checkout will charge. There is no ongoing free plan — new accounts start on the [14-day free trial](/account/plans-and-limits), and when it ends you upgrade to Starter or Pro to continue sending.
* **Starter** — For teams just getting started with WhatsApp for Business.
* One organization workspace
* 1,000 included billable conversations / month
* Shared team inbox
* Templates and HubSpot flows
* Email support
* **Pro** — For growing teams scaling WhatsApp automation.
* Everything in Starter
* 2,500 included billable conversations / month
* Priority support
* Channel analytics
* API access
* **Enterprise** — For organisations needing advanced support and bespoke solutions.
* Everything in Pro
* Advanced support
* Bespoke solutions
Flowella plan pricing only. Meta bills WhatsApp conversation fees separately — see [Pricing and conversation categories](/account/pricing-and-conversation-categories).
### Tiered pricing display
The Billing page renders your plan's **expanded pricing tiers** — base subscription plus any tiered overage rates — alongside a **payment summary** showing the most recent invoice and next renewal date. If you're on Starter or Pro, this is where you can see at a glance what you'd pay for an extra block of conversations.
### Usage metering and Stripe meter health
Flowella reports your monthly conversation count to Stripe as a usage meter. The Billing page surfaces a **meter health** indicator so you can confirm the count Stripe sees matches the count Flowella has recorded. If a discrepancy is detected (meter drift), the page shows a warning and Flowella automatically reconciles in the background. If the warning persists for more than a billing cycle, contact support — it usually means a webhook between Stripe and Flowella has been blocked.
## Managing an existing subscription
Once you have an active subscription, **Settings → Billing** shows a **Manage subscription** button that opens the **Stripe customer portal** in a new tab. From there you can:
* Update card details
* Download invoices
* Switch plans
* Cancel the subscription
Changes made in the portal are reflected in Flowella shortly after.
## Subscription states
Your subscription is always in one of these states:
| Status | What it means | What you can do |
| ------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Trialing** | You are inside the 14-day free trial provisioned at signup | Full access, capped at 5,000 outbound messages — see [Plans and limits](/account/plans-and-limits) |
| **Active** | Subscription is paid and current | Full access to features for that plan |
| **Past due** | A payment failed and Stripe is retrying | Existing data is intact; some actions may be limited until payment succeeds |
| **Canceled** | Subscription has been cancelled | The org reverts to limited access at the end of the paid period |
**Trialing** and **Active** behave the same way for what you can do in the app.
## What is locked when a subscription lapses
If your subscription becomes past due or is cancelled and the period ends, paid features are restricted. You will still be able to:
* Sign in and view your data
* Reach the Billing page to fix payment
You will not be able to send new messages, publish new templates, or use the API on paid endpoints until billing is restored.
Your contacts, opt-out list, conversation history, and configuration are preserved while a subscription is paused. Nothing is deleted automatically.
## Plans
Flowella offers a 14-day free trial and three paid tiers:
* **Free trial** — 14 days of full access at signup, then upgrade to keep sending. There is no ongoing free plan
* **Starter** — small teams
* **Pro** — growing programmes
* **Enterprise** — large or regulated deployments
For limits and feature differences, see [Plans and limits](/account/plans-and-limits) and [flowella.io/pricing](https://flowella.io/pricing).
If you need an annual contract, custom volume, or a security review for Enterprise, contact [sales](https://flowella.io/contact).
## Related
What each plan includes, trial cap, and how overage works.
How Meta charges are separate and how Flowella usage is counted.
Track conversation count and remaining allowance in real time.
What's blocked when a payment fails and how to restore access.
The separate card Meta uses for WhatsApp delivery fees.
Only Owners can change billing.
# Logging in to Flowella
Source: https://knowledge.flowella.io/account/login
Sign in to Flowella with a password or magic link, reset a forgotten password, and learn how the bot-protection check on the login page works.
This page covers everything you need to access your Flowella account: signing in with a password or magic link, resetting a forgotten password, and what the security check on the login page is doing.
## Where to log in
Open [app.flowella.io](https://app.flowella.io) and click **Log in**. If you are already signed in, you will be redirected to your most recent organisation.
## Sign-in options
### Password
1. Enter your work email and password.
2. Complete the security check on the form (this protects login from automated abuse).
3. Click **Log in**.
If your password is correct, Flowella signs you in and takes you to your organisation's dashboard.
### Magic link
If you would rather not use a password, request a one-time link instead:
1. On the login page, click **Email me a magic link**.
2. Enter your work email.
3. Open the email Flowella sends and click the link.
Magic links are single-use and expire shortly after they are sent. If a link expires, just request a new one.
Magic links sign you into the same account as your password. They do not create a separate account.
## Forgotten password
1. On the login page, click **Forgot your password?**.
2. Enter your work email.
3. Open the **Reset your password** email and click the link.
4. Choose a new password.
If the email does not arrive within a couple of minutes, check your spam folder. The link is single-use; request another if you need to.
## Why there is a security check on the form
The login, register, and password-reset forms include an automated **bot-protection challenge** (Cloudflare Turnstile). Most users will not see anything beyond a brief loading spinner — it runs invisibly. If your network or browser blocks it, you may see a small widget asking you to confirm you are human.
If the check fails repeatedly:
* Disable any browser extensions that block Cloudflare scripts.
* Try a different browser or network.
* Contact [support](https://flowella.io/support) if the problem persists.
## Staying signed in
Flowella keeps you signed in across sessions on the same browser. To sign out, open the user menu in the top-right of the app and click **Log out**.
Have multiple organisations? Use the org switcher in the top-left of the app to move between them without logging out.
## Related
Change your name, avatar, phone, locale, and password. Manage active sessions.
Invite teammates, accept invites, and understand what each role can do.
First-time setup after you sign in — connect Meta and HubSpot.
Common sign-in, Meta, and HubSpot connection issues.
# Meta integration settings
Source: https://knowledge.flowella.io/account/meta-integration
Manage your connected WhatsApp Business Accounts and phone numbers, re-authorise Meta when tokens expire, and review channel-level settings.
![Flowella WhatsApp Meta integration settings]()
This page covers the **Settings → Meta** screen in Flowella, which is where you manage your connection to Meta and the WhatsApp Business Accounts (WABAs) and phone numbers attached to your org.
For the initial connection during onboarding, see [Display name & profile](/meta/profile-setup). For the URL pattern and switching between channels, see [Multi-channel](/essentials/multi-channel).
## Who can manage Meta settings
Only **Owners** and **Admins** can change Meta integration settings. Members see the page but cannot reconnect or modify channels.
## What you see on Settings → Meta
The page lists every WABA connected to your org, and under each WABA, every phone number. For each phone number you can see:
* Display name
* Verification status
* Quality rating (as reported by Meta)
* Whether Flowella is currently subscribed to incoming-message webhooks
## Reconnecting Meta
Meta access tokens can expire — typically because a user permission was revoked, the connected user changed role at the company, or Meta required re-authorisation. When that happens, Flowella shows a banner prompting you to reconnect.
On **Settings → Meta**, click **Reconnect WhatsApp**.
Meta opens its Embedded Signup popup. Sign in with a Facebook account that has admin access to the Meta Business and the WABA.
Approve the scopes Flowella requests. These are the same scopes used during onboarding.
After the popup closes, the channel list refreshes. Confirm every WABA and phone number you expect is listed.
## Adding a new WABA or phone number
You can add more channels at any time:
* **A new WABA** — click **Connect WhatsApp** and run through Meta's Embedded Signup again. Pick the WABA you want to add.
* **A new phone number on an existing WABA** — add the number in Meta Business Manager first (Meta requires verification on Meta's side), then refresh the channel list in Flowella.
See [Multi-channel](/essentials/multi-channel) for how shared and per-channel settings work.
## Changing a display name or business profile
Display name, profile picture, address, and "About" text are configured per phone number. See [Display name & profile](/meta/profile-setup) for the full walk-through.
## Disconnecting a channel
If you no longer need a phone number in Flowella:
1. Open **Settings → Meta**.
2. Find the phone number under its WABA.
3. Click **Disconnect**.
Disconnecting:
* Stops Flowella from sending or receiving messages on that number.
* Does not delete templates or conversation history (these are kept for audit and reporting).
* Does not affect the number in Meta Business Manager — it remains attached to the WABA.
To remove the number from Meta entirely, do that in Meta Business Manager.
If templates or messages stop working on a single channel, **Settings → Meta** is the first place to check. A red banner here usually means a re-auth is needed.
## Related
The order of business portfolio, verification, WABA, and phone setup.
Verify your Meta Business so display names and limits unlock.
Add and verify the numbers that power each channel.
The separate card Meta uses for WhatsApp delivery fees.
Each channel now uses its own Meta access token — relevant for multi-WABA orgs.
Use your existing WhatsApp Business app number with Flowella.
# Flowella Subscription Plans, Limits, and Billing
Source: https://knowledge.flowella.io/account/plans-and-limits
Understand Flowella's four subscription plans, how usage limits and overages work, and how Meta's WhatsApp fees are charged separately.
When you use Flowella with WhatsApp, you will see two distinct types of costs: your Flowella subscription (billed by Discover Digital via Stripe) and Meta's WhatsApp Business Platform fees (charged directly by Meta through your own WhatsApp Business or Meta Business account). This article explains how both work, what each plan includes, and answers the most common billing questions. For the latest pricing numbers, always refer to the live [Flowella pricing page](https://flowella.io/pricing).
## How billing works
Think of the two costs this way:
* **Flowella subscription** — the software licence and usage allowance. Covers access to the Flowella platform, the HubSpot integration, dashboards, and usage up to your plan's limits.
* **Meta (WhatsApp) fees** — network fees for delivering messages. Paid via your own WhatsApp Business or Meta Business account and charged separately by Meta.
Flowella does not mark up or resell Meta fees. You pay Meta directly and remain responsible for those costs.
## Subscription plans
Ideal for testing the Flowella experience for a limited period.
* **14-day free trial** provisioned automatically at signup
* **5,000 outbound messages** cap during the trial window
* "Powered by Flowella.io" watermark on messages
* Countdown banner in-app showing days remaining
* At expiry, upgrade to **Starter** or **Pro** to keep sending — there is no ongoing free plan, but everything you've built is preserved
For teams getting started with WhatsApp automation.
* **1,000 conversations per month**
* Overage at \$0.05 per extra conversation
* No Flowella watermark
* HubSpot Workflow component included
For growing teams scaling WhatsApp automation.
* **2,500 conversations per month**
* Everything in Starter
* Lower overage rate (\$0.04 per extra conversation)
For organisations needing bespoke support or higher usage.
* Everything in Pro
* Bespoke pricing and tailored usage limits
* May be governed by a separate order form or service agreement
[Contact the Flowella team](https://flowella.io/pricing) to discuss.
The Free Trial adds a "Powered by Flowella.io" watermark to all WhatsApp messages. The trial is **hard-capped at 5,000 outbound messages** — unlike paid plans, the trial does **not** allow overage. Once the cap is hit, or the 14-day window ends, outbound sends are blocked until you upgrade. Inbound messages and replies continue to work.
## Trial lifecycle and usage alerts
When you sign up, Flowella creates a 14-day trial window stored on your billing record. During the trial:
* The dashboard and billing page show a **trial countdown** and the date the trial ends.
* Flowella sends a **`usage_soft_50` alert** (in-app notification and email) when you've used 50% of your 5,000-message trial cap. This is your prompt to plan for upgrading if you're trending toward the cap.
* The trial cap is enforced at send time: once you hit 5,000 outbound messages, the next send is blocked with a clear error and a link to upgrade.
* At the end of day 14, the trial expires. Outbound sending is blocked until you upgrade to **Starter** or **Pro** — there is no ongoing free plan. Your configuration, templates, and Flows are all preserved, so upgrading picks up exactly where you left off. If you need more time to evaluate, contact the team to ask about a trial extension.
Upgrading inside the trial window stops the countdown immediately and switches you to your chosen plan's allowance. Any messages already sent during the trial do **not** count against your new plan's monthly allowance.
## What counts as a conversation
In Flowella, usage is measured in **WhatsApp conversations**. A conversation is a single WhatsApp interaction between your business number and an end user that Flowella sends or manages — typically aligned with WhatsApp's own conversation or session concept. Multiple messages within a single 24-hour customer service window are generally treated as one conversation from a billing perspective.
Meta is transitioning to per-message billing for template messages, and Flowella may adjust its own usage counting over time. Check the Flowella dashboard and pricing page for the current definition.
## Included usage and overages
Each plan includes a set number of conversations per month. If you exceed your allowance:
* Flowella does **not** typically hard-stop your flows mid-cycle.
* Additional usage is billed as **overage** at your plan's per-conversation rate, usually at the end of your billing cycle.
Usage is subject to a **fair use policy**. Extremely high volumes or behaviour that resembles spam may trigger a review, a request to move to a higher tier, or — in extreme cases — rate limiting or suspension. If you are planning a large campaign, contact the Flowella team in advance so you are on the right plan.
You can monitor your usage at any time from the Flowella dashboard.
## Trials, renewals, and cancellations
* **Free trial** starts when you create your account or activate a trial plan. It runs for a limited period or until you hit the usage cap — whichever comes first. At the end of the trial, upgrade to a paid plan to keep your flows live.
* **Paid plans** are billed in advance on a monthly billing cycle and auto-renew each month unless you cancel.
* **Cancellation** takes effect at the end of your current billing period. You keep full access until then and are not billed again after that date.
Flowella charges are processed securely via Stripe. Your card details are handled by Stripe and are not stored in the Flowella application.
## Meta (WhatsApp) fees
Flowella subscription fees do not include WhatsApp message delivery costs. Those are charged by Meta for use of the WhatsApp Business Platform.
Meta historically used a conversation-based model where you pay per 24-hour conversation window, with categories such as marketing, utility, service, and authentication. Meta is now transitioning to per-message billing for template messages, with rates depending on category and country. This change is being rolled out across providers, so always check your own rate card for the current structure.
Key points about Meta fees:
* Rates vary by **country/region** and **message category**.
* Some replies within the 24-hour customer service window may be free; proactive templates outside that window are usually chargeable.
* Meta bills these fees via your WhatsApp Business account or through your Business Solution Provider.
To see your Meta charges, go to **Meta Business Manager → WhatsApp Manager → Billing**. There you can view your rate card for different countries and categories, billing invoices, and spending caps.
## Frequently asked questions
Yes. Conversation allowances reset at the start of each new billing month for your subscription.
Yes. You can upgrade or downgrade at any time. Upgrades usually take effect immediately with a prorated charge. Downgrades take effect at the next renewal date.
Flowella does not usually hard-stop your flows. Additional conversations are billed as overage at your plan's per-conversation rate, charged at the end of your billing cycle. If you expect high volumes, contact the team to move to a higher tier in advance.
Meta bills WhatsApp fees separately through your WhatsApp Business account. To view invoices and your rate card, go to **Meta Business Manager → WhatsApp Manager → Billing**. Flowella has no visibility into or control over those charges. To add or change the card Meta charges, see [Meta payment method](/meta/payment-method).
## Related
Manage subscription, payment method, and Stripe portal.
Meta conversation categories and how usage is counted.
Current cycle counter, per-channel breakdown, and historical cycles.
Add the card Meta uses for WhatsApp delivery fees.
Meta's per-day send caps and how they scale with quality.
What Meta watches and how to keep your channel out of low quality.
# Pricing and WhatsApp conversation categories
Source: https://knowledge.flowella.io/account/pricing-and-conversation-categories
How Meta's conversation-based pricing works, how it interacts with your Flowella subscription, and why Meta charges and Flowella usage are billed separately.
WhatsApp is billed per **conversation**, not per message — and the price depends on the conversation's **category**. This page explains how Meta's pricing works, how it lines up with your Flowella plan, and why you see two separate bills.
For plan sizes and Flowella overage rates, see [Plans & limits](/account/plans-and-limits). For invoice mechanics on the Flowella side, see [Billing](/account/billing).
## Two separate bills
Using Flowella with WhatsApp always involves **two costs**:
| Bill | Who charges you | What it covers |
| ------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Flowella subscription** | Discover Digital (via Stripe) | The Flowella platform, HubSpot integration, dashboards, and your monthly conversation allowance. |
| **Meta WhatsApp fees** | Meta directly, via your own WhatsApp Business / Meta Business account | Network delivery of every WhatsApp conversation, priced by category and country. |
Flowella does not resell or mark up Meta charges. Meta bills you directly through the payment method on your WhatsApp Business Account. Flowella never sees or processes those funds.
**One trigger, two charges.** Every time Meta opens a billable conversation, that same conversation **also counts toward your Flowella monthly usage**. If you're inside your Flowella allowance, the Flowella side is "free" for that conversation (it's covered by your subscription). If you're over your allowance, you'll see a Flowella overage charge **in addition to** the Meta fee.
## Conversation categories
Meta groups every conversation into one of four categories. The category is decided by the **template you send first** (for business-initiated conversations) or by **who started the conversation** (for user-initiated ones).
| Category | When it applies | Typical cost | Notes |
| ------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------- |
| **Marketing** | You send a Marketing-category template — promos, offers, re-engagement | Highest tier | Requires explicit opt-in; subject to frequency capping by Meta. |
| **Utility** | You send a Utility-category template — order updates, alerts, reminders tied to a specific transaction | Mid tier | Must relate to an existing transaction or request from the user. |
| **Authentication** | You send an Authentication template — OTPs and verification codes | Lowest tier | Strict content rules; no marketing language allowed. |
| **Service** | The user messaged you first, inside the 24-hour customer service window | Free in most markets (as of 2025 Meta pricing changes) | Replies to inbound messages within 24 hours of the user's last message. |
Meta updates these rates and rules periodically. The latest official rates per country are on the [Meta WhatsApp pricing page](https://developers.facebook.com/docs/whatsapp/pricing). The categories themselves can change too — Meta has been phasing the **Service** category in and out of "free" status by market.
### Why category matters
* **Cost per conversation** is set entirely by Meta's category-and-country matrix. The same template sent to the UK, Brazil, and India will have three different unit costs.
* **Approval rules** differ. A Utility template containing Marketing-style content will be rejected — or worse, approved and then **re-categorised** mid-campaign, which silently changes your unit cost.
* **Opt-in requirements** differ. Marketing requires explicit, recent opt-in. Utility and Authentication are more permissive but only for genuine transactional content.
### The 24-hour customer service window
When a contact messages you, Meta opens a **24-hour service window**. Inside that window:
* You can reply with **free-form messages** (no template needed).
* The conversation is categorised as **Service** and is often free.
Outside the 24-hour window, you must send a **template** to re-open the conversation, and the template's category sets the new conversation's category and price.
See [Inbox](/app/inbox) for how Flowella surfaces the service window in the UI.
## How Meta charges and Flowella usage line up
A single illustrative example on a **Starter plan** (2,000 conversations/month):
| Scenario | Meta charges | Flowella counter | Flowella charge |
| ------------------------------------------------------- | -------------------------------- | -------------------------------- | ---------------------------- |
| A contact messages you first; you reply within 24 hours | Service conversation (often \$0) | +1 conversation | Covered by subscription |
| You send a Utility template (order shipped) | Utility rate × country | +1 conversation | Covered by subscription |
| You send a Marketing campaign template | Marketing rate × country | +1 conversation | Covered by subscription |
| You send conversation 2,001 in the month | Same Meta rate as above | +1 conversation (over allowance) | \~\$0.04 overage on Flowella |
**Key points:**
* Every billable Meta conversation creates exactly one Flowella usage tick. There is no "Meta-only" path that bypasses Flowella metering.
* Flowella overage is charged **in addition to** the Meta fee, not instead of it.
* Free Meta conversations (Service-window replies, where Meta's rate is \$0) still count as one Flowella conversation. They use your monthly allowance even though Meta charges nothing.
## Monthly usage does not roll over
Your Flowella plan includes a fixed number of conversations per calendar month. **Unused conversations expire at the end of the month and do not carry forward.**
* A Starter plan that uses 1,200 of 2,000 conversations in May does **not** start June with 2,800. June starts at 2,000.
* The reset happens on your **billing anniversary**, not strictly on the 1st of the month. The Settings → Usage page shows your exact cycle dates.
* Overage charges are calculated **per month**. Going over by 500 conversations in May does not let you "save" the next month — June starts at 2,000 again, and overage is recalculated from zero.
If you regularly use 80% or more of your allowance, upgrading to the next plan is usually cheaper than paying overage on the current one. The [Plans & limits](/account/plans-and-limits) page has the comparison.
## Checking what you've spent
* **Meta charges** — visible in your Meta Business Manager → Billing. Flowella does not display Meta's invoiced amount.
* **Flowella conversation count** — visible in Settings → Usage, broken down by channel and by month. Updated in near real time.
* **Flowella invoice** — visible in Settings → Billing. Includes subscription + any overage from the previous cycle.
## Common questions
Flowella counts that as one conversation against your monthly allowance, the same way every other conversation counts. Meta usually charges \$0 for that Service conversation, but Flowella's metering is conversation-based, not Meta-spend-based.
Yes — go to [Analytics](/app/analytics) and group by category. This shows your conversation mix (Marketing / Utility / Authentication / Service), which is what drives the Meta side of your bill.
Meta sometimes re-categorises a template after it's been live for a while if the content drifts from the approved category. Re-categorisation changes the unit cost on the Meta side. The Flowella usage count is unaffected. See [Template rejected](/troubleshooting/template-rejected) for prevention tips.
Yes, but only from Meta's side — set spending limits on your WhatsApp Business Account in Meta Business Manager. Flowella does not have a separate Meta-spend cap.
Meta currently treats conversations that start from a **free entry point** (some ad formats, some referrals) as free for 72 hours. Flowella still counts these as one conversation against your allowance. See [Click-to-WhatsApp ads](/campaigns/click-to-whatsapp-ads).
Always cross-check current Meta rates on the [official pricing page](https://developers.facebook.com/docs/whatsapp/pricing) before launching a high-volume campaign. Meta has changed pricing and category rules several times in the last 18 months.
## Related
Flowella's monthly conversation allowances and overage rates.
Manage subscription, payment method, and Stripe meter health.
Track your current-cycle conversation count in real time.
How the category you submit drives both review and pricing.
Meta's per-day send caps that interact with conversation pricing.
Add the card Meta uses for WhatsApp delivery fees.
# Outbound message analytics
Source: https://knowledge.flowella.io/api-reference/analytics/outbound-message-analytics
/api-reference/openapi.json get /v1/analytics
Aggregates outbound message counts and rates by status for a date range.
# Create or update contact
Source: https://knowledge.flowella.io/api-reference/contacts/create-or-update-contact
/api-reference/openapi.json post /v1/contacts
# List contacts
Source: https://knowledge.flowella.io/api-reference/contacts/list-contacts
/api-reference/openapi.json get /v1/contacts
# Set or clear per-channel WhatsApp opt-out
Source: https://knowledge.flowella.io/api-reference/contacts/set-or-clear-per-channel-whatsapp-opt-out
/api-reference/openapi.json post /v1/opt-outs
`action: set` creates or reactivates an opt-out for the given channel and phone. `action: clear` revokes it. Idempotent clears are safe.
# List conversations
Source: https://knowledge.flowella.io/api-reference/conversations/list-conversations
/api-reference/openapi.json get /v1/conversations
# API introduction
Source: https://knowledge.flowella.io/api-reference/introduction
Authentication, base URL, error codes, pagination, rate limits, and idempotency keys for the Flowella REST API v1 — all you need before your first call.
The Flowella REST API lets you send WhatsApp messages, manage contacts and opt-outs, list and bulk-send templates, and pull analytics — programmatically. This page covers everything you need to know before calling an endpoint.
The full endpoint reference lives in the **API reference** sidebar (auto-generated from the [OpenAPI spec](/api-reference/openapi.json)).
## Base URL
```
https://api.flowella.io/v1
```
All v1 endpoints live under this canonical base — for example `https://api.flowella.io/v1/messages`.
The API previously lived on the app host at `https://app.flowella.io/api/v1/...`. Legacy requests to that path are permanently redirected (`308`) to the canonical `https://api.flowella.io/v1/...`, preserving the method and body — so existing integrations keep working. Update your base URL when you get a chance to skip the extra hop.
## Authentication
Every request needs an API key in the `Authorization` header:
```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```
Keys are organisation-scoped — they act on a single Flowella org and inherit the permissions of an Admin in that org.
Treat keys like passwords. Never commit them to source control, never paste them in chat or shared docs, and rotate them when teammates leave the org. See [Settings → API keys](/settings/api-keys) for rotation steps.
### Creating a key
You need the **Owner** or **Admin** role to manage API keys.
1. Go to **Settings → API keys** in the Flowella app.
2. Click **Create key** and give it a memorable name.
3. Copy the key once — it is shown only at creation time.
Treat keys like passwords: never commit them to source control, never paste them in chat, and rotate them when teammates leave the org.
### Verifying a key
Hit the ping endpoint to confirm a key is valid:
```bash cURL theme={null}
curl https://api.flowella.io/v1/ping \
-H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```
```js Node.js theme={null}
await fetch("https://api.flowella.io/v1/ping", {
headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});
```
```python Python theme={null}
import os, requests
requests.get(
"https://api.flowella.io/v1/ping",
headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)
```
A `200 OK` with `{ "ok": true, "organizationId": "…" }` means you are authenticated.
## Errors
All errors come back in a consistent envelope:
```json theme={null}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}
```
| HTTP status | When you'll see it |
| ----------- | ---------------------------------------------------------------------------------- |
| `400` | Validation failed, malformed body, or upstream Meta rejection |
| `401` | Missing or invalid API key |
| `402` | Payment required — your subscription does not cover the action |
| `403` | Forbidden — for example, sending to an opted-out contact, or Meta is not connected |
| `404` | The requested channel or resource does not exist |
| `429` | Rate limited — slow down |
The `error.code` field is stable and safe to switch on programmatically. The `error.message` is human-readable and may change.
## Rate limits
API keys are rate-limited per organisation. If you exceed the limit you will get a `429` with code `RATE_LIMITED` and the message `Too many requests`. When present, the `Retry-After` response header tells you how many seconds to wait. Back off and retry with exponential delay.
If you are running large bulk sends, prefer **`POST /v1/templates/send`** with the `throttlePerHour` parameter — Flowella enforces the throttle server-side, so you do not need to pace requests yourself.
## Idempotency keys
Bulk template sends are asynchronous. `POST /v1/templates/send` validates the request, queues it durably, and returns `202 Accepted` immediately:
```json theme={null}
{
"id": "v1ts-0123456789abcdef",
"status": "accepted"
}
```
Flowella delivers the batch in the background and retries temporary WhatsApp errors automatically. Recipients are processed individually, so one invalid number does not block the rest of the batch. Follow delivery progress on the template's **Statistics** tab in the app.
Because delivery happens after the response, retries need to be safe. Pass an `Idempotency-Key` header (up to 200 characters) that uniquely identifies each batch:
```bash theme={null}
curl -X POST "https://api.flowella.io/v1/templates/send" \
-H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: campaign-2026-08-31-launch" \
-H "Content-Type: application/json" \
-d '{
"templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
"whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
"recipients": [{ "phone": "+15551234567" }]
}'
```
Repeats of the same key within seven days return the original job `id` instead of creating a new send. You can safely retry a request after a timeout or network error without messaging anyone twice.
If you omit the header, Flowella derives a key from the request body. An identical batch submitted twice in quick succession is therefore not double-sent. An explicit key is still safer, because any change to the body (even reordering recipients) produces a new derived key.
## Pagination
List endpoints (`/conversations`, `/contacts`, `/templates`) use **cursor pagination**:
* Pass `limit` (1–100, default 25) and an optional `cursor`.
* The response contains `items` and, when there are more results, a `nextCursor`.
* Pass `nextCursor` back as the `cursor` parameter to fetch the next page.
* When `nextCursor` is missing, you have reached the end.
```bash theme={null}
curl "https://api.flowella.io/v1/conversations?limit=50" \
-H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```
## Date and time
All timestamps are ISO 8601 strings in UTC (for example `2025-01-15T14:30:00.000Z`). Where the API accepts dates, both date-only (`2025-01-15`) and full ISO 8601 are coerced server-side.
## Phone numbers
Pass phone numbers in **E.164** form (`+15551234567`) where possible. Flowella will normalise common variations server-side, but E.164 is safest.
## Channels
Many endpoints accept a `whatsappChannelId`. If your org has a single channel and you omit it, Flowella uses your default channel. If you have multiple channels, pass the ID explicitly to avoid sending from the wrong sender.
For the full URL pattern and channel switching, see [Multi-channel](/essentials/multi-channel).
## OpenAPI spec
The machine-readable spec lives at:
```
/api-reference/openapi.json
```
Drop it into Postman, Insomnia, or your code generator of choice.
Building an integration? Pair this page with [Webhooks](/api-reference/webhooks) to react to events instead of polling for state.
# Send WhatsApp text message
Source: https://knowledge.flowella.io/api-reference/messages/send-whatsapp-text-message
/api-reference/openapi.json post /v1/messages
# Ping (auth check)
Source: https://knowledge.flowella.io/api-reference/system/ping-auth-check
/api-reference/openapi.json get /v1/ping
Returns `ok` and the organization id for the resolved API key. Use to verify credentials.
# List WhatsApp templates
Source: https://knowledge.flowella.io/api-reference/templates/list-whatsapp-templates
/api-reference/openapi.json get /v1/templates
# Queue template send job
Source: https://knowledge.flowella.io/api-reference/templates/queue-template-send-job
/api-reference/openapi.json post /v1/templates/send
Accepts a bulk template send and processes it in the background. The request is validated at the door, queued durably, and returns `202 Accepted` immediately with a job id. Send an `Idempotency-Key` header to make retries safe: repeats of the same key within seven days return the original job id instead of sending the batch again. Without the header, Flowella derives a key from the request body, so an identical batch submitted twice in quick succession is not double-sent. Recipients are processed individually, so one invalid number does not block the rest of the batch.
# Outbound webhooks
Source: https://knowledge.flowella.io/api-reference/webhooks
Subscribe to message, conversation, opt-out, and template events. Verify HMAC signatures, handle retries, and avoid duplicate processing.
Outbound webhooks let your systems react to events in Flowella in near real-time, without polling the API. You configure a URL and a list of event types, and Flowella POSTs a signed JSON payload to that URL whenever one of those events fires.
## Configuring a webhook
You need the **Owner** or **Admin** role.
In the Flowella app, go to **Settings → Webhooks**.
Click **Add webhook**, paste the public HTTPS URL of your endpoint, and pick the event types you want to receive.
Flowella generates a unique signing secret for the webhook. Copy it — you will use it to verify incoming requests.
Click **Send test** to dispatch a `webhook.test` payload immediately. Check your endpoint received it and responded with a 2xx.
## Event types
You can subscribe to any of these product events:
| Event | When it fires |
| ------------------------- | ----------------------------------------------------------------------- |
| `message.received` | An inbound WhatsApp message has arrived from a contact |
| `message.sent` | Flowella has accepted your outbound message and submitted it to Meta |
| `message.delivered` | Meta confirmed the message was delivered to the recipient's device |
| `message.read` | The recipient opened the message |
| `message.failed` | Meta returned a failure for the message |
| `conversation.opened` | A conversation has moved into the open state |
| `conversation.closed` | A conversation has been closed |
| `optout.created` | A contact opted out on a specific channel |
| `template.status_updated` | Meta changed a template's status (approved, rejected, paused, disabled) |
`webhook.test` is sent only when you click **Send test** — you do not subscribe to it explicitly.
## Request format
Flowella POSTs a JSON body to your URL with these headers:
```http theme={null}
POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella-Webhooks/1
X-Flowella-Signature:
```
Payloads are capped at **256 KB**. Larger objects are summarised — use the API to fetch the full record by ID if you need it.
The body shape varies by event but always includes:
```json theme={null}
{
"event": "message.delivered",
"timestamp": "2025-01-15T14:30:00.000Z",
"organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
"data": { "...event-specific fields..." }
}
```
## Verifying signatures
Every request includes an `X-Flowella-Signature` header. The value is the **HMAC-SHA256 hex digest** of the **raw UTF-8 request body** keyed with your webhook's signing secret.
Verify before processing:
```js theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, signatureHeader, secret) {
const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(signatureHeader, "hex");
return a.length === b.length && timingSafeEqual(a, b);
}
```
```python theme={null}
import hmac, hashlib
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header)
```
Always sign over the **raw body bytes** before any JSON parsing or middleware reformats the payload. If your framework reserialises JSON, the signature will not match.
## Responses, retries, and timeouts
* **Timeout**: Flowella waits up to **10 seconds** for your endpoint to respond.
* **Success**: any `2xx` response is treated as successful delivery.
* **Retries**: failed deliveries are retried up to **3 attempts** with backoff.
* **Auto-disable**: if a webhook accumulates **10 consecutive failures**, Flowella deactivates it. You will need to re-enable it from **Settings → Webhooks** after fixing your endpoint.
Your endpoint should return as fast as possible — defer any heavy processing to a background queue on your side.
## Idempotency
Webhooks may be retried, so the same logical event can arrive more than once. To process safely:
* Use the `data.id` of the event (or a derived key like `event + data.messageId`) as an idempotency key.
* Keep a short-lived cache of processed keys (a few hours is enough for retries).
* Treat duplicates as no-ops.
## Listing and managing deliveries
**Settings → Webhooks** shows recent delivery attempts per webhook, including:
* Timestamp
* Event type
* Response status
* A truncated response body (up to \~1 KB) for debugging
If a webhook is deactivated due to repeated failures, the same page lets you re-enable it.
## Local development
The simplest way to develop against webhooks locally is to forward a public tunnel (for example, ngrok or Cloudflare Tunnel) to your dev server and point the webhook URL at the tunnel host. Use **Send test** to fire payloads on demand without waiting for real WhatsApp activity.
Need to react to events that aren't on the list? Tell us at [support](https://flowella.io/support) — we add events as customers ask for them.
## Related
Configure endpoints, signing secrets, and retries in the app.
Auth, errors, pagination, and rate limits for the REST API.
Create and rotate the bearer tokens your endpoint may need.
The same events delivered into the in-app feed and email.
# Channel analytics, template performance, and usage
Source: https://knowledge.flowella.io/app/analytics
Track conversations, outbound messages, opt-outs, template performance, and usage trends per channel, with date-range presets, drill-down, and CSV export.
![Flowella analytics]()
Analytics gives you per-channel reporting on conversations, outbound messaging, opt-outs, template performance, and usage. Use it to monitor delivery quality, spot trends, and pull data into spreadsheets when you need to share results.
## How to open it
Analytics is a channel-scoped page. Pick the channel you want, then go to:
```text theme={null}
/{org}/{waba}/{phone}/analytics
```
Or open **Analytics** from the left navigation while you have a channel selected.
For how channel scoping works, see [Multi-channel](/essentials/multi-channel).
## Date range
The page includes three presets and a custom range:
* **Last 7 days**
* **Last 30 days** (default)
* **Last 90 days**
* **Custom** — pick any start and end date
Granularity is chosen automatically based on the range:
| Range | Granularity |
| -------------- | ----------- |
| Up to 45 days | Day |
| 46 to 120 days | Week |
| Over 120 days | Month |
## Metrics
### Channel summary
Three headline numbers for the selected range and channel:
* **Delivery rate** — percentage of outbound messages Meta confirmed delivered.
* **Read rate** — percentage of delivered messages the recipient opened.
* **Failure rate** — percentage of outbound messages that failed. The number renders in **red only when failure rate is above 5%** and there has been outbound activity in the range. With no activity, the page shows a neutral "No activity in this range" message rather than a misleading red 0.0%.
### Conversations over time
A line chart of distinct conversations per day, week, or month. A "conversation" is any thread with at least one inbound or outbound message in that bucket.
### Opt-outs over time
New opt-outs per bucket. Useful for spotting spikes that might correlate with a specific campaign or template.
### Usage over time
Total outbound messages per bucket, used for capacity planning against your [plan limits](/account/plans-and-limits).
### Templates table
A per-template breakdown for the selected range:
* **Send count**
* **Delivery rate**
* **Read rate**
Sort the table to find your best- and worst-performing templates.
### Per-template drill-down
Click any row in the **Templates table** to open a side sheet with **100% of the send logs** for that template in the current date range (not a sampled subset).
The side sheet shows:
* **One row per send**, with recipient phone (masked), send time, **status** (Queued, Sent, Delivered, Read, Failed, Suppressed), and the same plain-English **Details** column as the template's own Statistics tab — see [Templates → Per-send Details column](/app/templates#per-send-details-column). Details resolves the most common Meta delivery failures into readable text — `131049` (per-user marketing limit), `131050` (contact opted out of marketing), `131048` (spam/quality block on your number), `131063` (marketing disabled on this Cloud API config), and `131064` (template classification limit) — using the same copy shown under failed bubbles in the [inbox](/app/inbox#failed-message-bubbles). Anything Flowella doesn't have a mapping for falls back to Meta's own wording with the code in parentheses.
* **Search** by phone or message content.
* **Sort** by any column (defaults to send time, newest first).
* **Status filter chips** at the top to narrow to a single outcome — for example, only **Failed** to triage delivery issues.
#### Per-template export
The drill-down side sheet has its own **Export** dropdown that produces a **CSV** or **PDF** for just this template — independent of the main page-level export described below. Use it when you need to share or audit performance for one template without pulling the whole channel's data.
## Exporting data
Click the **Export** dropdown to download the data behind the charts and table. You can pick:
* **CSV** — one file containing the five metrics (conversations, messages, opt-outs, templates, usage).
* **PDF** — a snapshot of the current charts for sharing.
Exports are produced in the background. Flowella shows "Export queued" while preparing it and "Export ready" with a download link when done. You can leave the page and come back — the link is also delivered as a notification.
## Sample data
If you have no WhatsApp channel connected yet, Analytics still renders with **illustrative numbers** behind a "Sample data" callout. This lets you preview the page without committing to set-up.
Pair the templates table with [the templates page](/app/templates) to identify low-read-rate templates that may need rewording or category changes.
## Related
The 7-day snapshot that feeds the org home page.
Surface WhatsApp activity alongside email, calls, and meetings.
What Meta watches and how delivery / read rates feed into it.
Meta's per-day send caps that interact with these metrics.
# Flowella dashboard: usage, WhatsApp snapshot, channels
Source: https://knowledge.flowella.io/app/dashboard
What you see when you sign in to Flowella: usage counters, a 7-day WhatsApp snapshot, connected channels, and HubSpot integration and forms status.
![Flowella dashboard]()
The Dashboard is the first page you see after signing in. It gives you a one-screen view of your billing, your WhatsApp activity over the last 7 days, your connected channels, your HubSpot integration, and the forms Flowella is syncing.
## How to open it
Sign in to Flowella. The Dashboard is the home page of every organisation, at `/{org}/dashboard`. You can also click the Flowella logo in the top-left from any page to return here.
## What the Dashboard shows
The page is laid out as a grid of cards. The exact set you see depends on what is connected, but the standard set is:
Current plan and a shortcut to manage your subscription. See [Billing](/account/billing).
A snapshot of activity on your active channel: conversations, total outbound messages, delivery rate, read rate, and failure rate.
The number of WhatsApp channels connected to your org and a shortcut to add another. See [Multi-channel](/essentials/multi-channel).
Connection status for HubSpot and a quick link to integration settings.
The number of HubSpot forms Flowella is tracking. See [Forms](/app/forms).
Live counts pulled from Meta and your Flowella drafts — for example, "**12 approved · 3 drafts**" — with a shortcut into the templates list. If Meta doesn't respond within 8 seconds, the card falls back to the last known counts.
Shortcuts to common tasks: open the inbox, create a template, view analytics.
Each card shows an **"Updated …"** freshness line so you know how recent the numbers are. Data refreshes when you focus the tab and at most every 60 seconds.
## The WhatsApp snapshot
The WhatsApp card shows five metrics, all calculated over the **last 7 days** for your **active channel**:
* **Conversations** — distinct conversations that had at least one message in the period.
* **Total outbound** — messages sent from your channel.
* **Delivery rate** — percentage of outbound messages Meta confirmed delivered.
* **Read rate** — percentage of delivered messages the recipient opened.
* **Failure rate** — percentage of outbound messages that failed.
For longer ranges and per-template breakdowns, open [Analytics](/app/analytics).
If the active channel has had **no activity** in the last 7 days, the card shows a neutral **"No activity yet"** message instead of a row of zeros and a misleading 0.0% failure rate.
## Sample data when nothing is connected
If your org has no WhatsApp channel yet, the Dashboard still renders the layout but uses **illustrative numbers** with a "Sample data" callout. As soon as you connect a channel and send a few messages, the card switches to your real data.
## Switching channels
The WhatsApp snapshot reflects the **active channel**. To see numbers for a different channel, switch channels using the channel switcher in the top-left. See [Multi-channel](/essentials/multi-channel).
If a card shows "Unavailable", the underlying integration probably needs reconnecting. Most often that is HubSpot or Meta — check **Settings → HubSpot** or **Settings → Meta**.
## Related
Per-channel detail behind the 7-day dashboard snapshot.
Current-cycle conversation count and per-channel breakdown.
Open a conversation directly from the dashboard.
The bell icon and the operational events behind it.
# Entry points: tracked links, QR codes, and CTWA sources
Source: https://knowledge.flowella.io/app/entry-points
Create WhatsApp Link, QR code, and CTWA entry points in Flowella to send customers into a WhatsApp chat with a tracked link and per-source click counts.
An **entry point** is a source that sends customers into a WhatsApp conversation with your business — a link on your website, a QR code on a poster, or a Click-to-WhatsApp ad on Facebook or Instagram. Every entry point you create in Flowella gets its own tracked URL on `link.flowella.io`, its own click counter, and (for ads) its own attribution ID on the resulting conversation.
Use entry points when you want to know **which source drove a conversation**, not just that a conversation happened.
## How to open Entry Points
Entry Points is an organisation-scoped page. From the left navigation, click **Entry Points** to open:
```text theme={null}
/{org}/entry-points
```
The page lists every entry point in the organisation with its type, the tracked URL, the click count, and when it was created.
## The three entry point types
A tracked link you paste anywhere: website buttons, email footers, social bios, SMS. Opens WhatsApp with a chat to your business number.
The same tracked link, rendered as a QR code you can download and print on packaging, posters, table tents, or business cards.
A source you attach to a **Click-to-WhatsApp** Facebook or Instagram ad. Flowella records Meta's click ID on the conversation for downstream attribution.
WhatsApp Link and QR code entry points are the Flowella-managed replacement for hand-built `wa.me` URLs. See [Click-to-chat](/campaigns/click-to-chat) for background on when to use each surface. CTWA entry points pair with the ad-side setup described in [CTWA Ads](/campaigns/click-to-whatsapp-ads).
## Create an entry point
Flowella opens a type picker with the three entry point types.
Choose **WhatsApp Link**, **QR code**, or **CTWA**. The form fields change to match.
Give the entry point a **name** you will recognise in reports (e.g. `Homepage FAB`, `Spring launch flyer`, `Instagram — Spring launch ad`). For WhatsApp Link and QR code, pick the WhatsApp channel the link should send customers to and optionally set a pre-filled first message.
Flowella generates the tracked URL on `link.flowella.io` and adds the entry point to the list. QR code entry points also get a downloadable QR image.
## Using the tracked URL
Every WhatsApp Link and QR code entry point has a tracked URL of the form:
```text theme={null}
https://link.flowella.io/
```
You can copy this URL from the Entry Points list and reuse the same one anywhere:
* **Website buttons and CTAs** — link a "Chat on WhatsApp" button at it.
* **Email footers and sales signatures** — paste it as a normal hyperlink.
* **QR code generators** — if you want to render your own QR (for a specific print size or brand style), point the generator at this URL rather than at a raw `wa.me` link.
* **Social bios and link-in-bio pages** — Instagram, TikTok, LinkedIn, X.
When someone taps the URL, `link.flowella.io` counts the click, then redirects them to WhatsApp (`wa.me`) with your business number and any pre-filled message. The customer lands in WhatsApp; you get a click counted against the entry point.
Create a separate entry point per placement — one for the homepage button, one for the email footer, one for each printed asset. That way the click counter tells you where conversations are coming from, not just that they exist.
## CTWA entry points
For a Facebook or Instagram Click-to-WhatsApp ad, create a **CTWA** entry point and use it as the source identifier for that ad campaign. When a customer taps the ad and starts a chat, Flowella stores Meta's `ctwa_clid` against the conversation so you can attribute it back to the ad in analytics and in HubSpot.
The ad itself is still built in Meta Ads Manager — Flowella does not create the ad for you. See [CTWA Ads](/campaigns/click-to-whatsapp-ads) for the full ad-side setup.
## Reading the click counter
The Entry Points list shows a **clicks** column per row. This counts every tap on the tracked URL, whether or not the person went on to send a message in WhatsApp.
Compare it against the conversations reported in [Analytics](/app/analytics) to see how many clicks turn into actual chats.
## Related guides
* [Click-to-chat](/campaigns/click-to-chat) — where to place WhatsApp Link and QR entry points
* [CTWA Ads](/campaigns/click-to-whatsapp-ads) — the ad-side setup that pairs with CTWA entry points
* [UTM tracking](/hubspot/utm-tracking) — how `ctwa_clid` and pre-filled codes flow into HubSpot
# Form design best practices for WhatsApp Flows
Source: https://knowledge.flowella.io/app/form-design-best-practices
Design HubSpot forms that render cleanly as WhatsApp Flows: label limits, choosing the right question type, and stopping clipped labels on iPhone.
Every field in your HubSpot form becomes a component in a WhatsApp Flow, and Meta caps how much label text each component can display. Labels longer than the cap get clipped on the customer's phone, most noticeably on iPhone.
The Flow still publishes, and the answers still reach HubSpot correctly. The only consequence is visual, which is why this is easy to miss until a real customer opens the form.
This page covers how to build HubSpot forms that read well on every device.
## The short version
Aim for 20 characters or fewer on dropdown and text fields. That is roughly three short words.
Under eight options reads better as radio buttons than a dropdown, and gives you a longer label.
Use a rich text element for the question and keep the field label itself short.
Android is more forgiving. If it reads correctly on iPhone, it reads correctly everywhere.
## What happens to your field labels
Each HubSpot field type maps to a WhatsApp Flow component, and each component has its own label allowance. The fields people use most are the tightest.
| HubSpot field | Renders as | Label allowance |
| ------------------- | -------------- | ------------------ |
| Dropdown select | Dropdown | 20 characters |
| Single-line text | Text input | 20 characters |
| Multi-line text | Text area | 20 characters |
| Radio select | Radio buttons | 30 characters |
| Multiple checkboxes | Checkbox group | 30 characters |
| Date picker | Date picker | 40 characters |
| Single checkbox | Opt-in | 120 characters |
| Rich text | Rich text | No practical limit |
Option labels within a dropdown, radio group or checkbox group get 30 characters each, with 300 characters available for an optional description underneath.
These are guidance rather than hard limits. Meta's own Flow builder shows a warning, not an error, and a Flow with long labels validates and publishes normally. Nothing is broken, and no data is lost. The label is simply shortened on screen.
## Why it looks fine on one phone and wrong on another
The character counts above are a guide, not a precise threshold. What actually decides whether a label is clipped is how much room the text has once the device has taken its share for padding, the chevron on a dropdown, and the customer's own font size setting.
That varies a lot. The same 33 character question can render in full on one Android handset, lose its last word on another, and be cut mid-word across two lines on an iPhone.
The practical consequences:
* **iPhone is the strictest surface.** Design for it and the rest follow.
* **Testing on one device is not enough.** A form that looks correct on your own phone can still be clipped for a large share of your audience.
* **Non-Latin scripts and wide characters run out of room sooner.** If you are collecting in Arabic, Hindi, Thai or Turkish, treat the character counts above as generous and aim shorter.
## Choosing the right question type
Most clipping problems come from using a dropdown where a dropdown was never the right control.
Set the field to **Radio select** in HubSpot. You get a 30 character label instead of 20, the label sits above the options as a block of text that wraps rather than being squeezed inside the control, and the customer answers with one tap instead of open, scroll, select, close.
This is Meta's own recommendation, and it resolves the majority of clipped labels on its own.
Long lists belong in a dropdown. A country list or a product catalogue as twenty radio buttons is a wall of text.
A dropdown holds up to 200 options. Radio and checkbox groups are capped at 20, so anything longer has to be a dropdown regardless of how the label reads.
**Multiple checkboxes** in HubSpot becomes a checkbox group, with the same 30 character label allowance as radio buttons and the same 20 option ceiling.
A two option dropdown is the worst case: the tightest label allowance on the shortest possible list, and two taps to answer a question that deserves one.
## Writing labels that fit
A WhatsApp Flow is a conversation, not a paper form. Short labels read better here even where there is room for more.
| Instead of | Try |
| --------------------------------------------- | -------------- |
| What is your preferred contact method? | Contact method |
| Which of our services are you interested in? | Service |
| What is your approximate annual budget? | Annual budget |
| Please select your preferred appointment date | Preferred date |
A few rules that keep labels tight without losing meaning:
* Drop the polite scaffolding. "Please select your" and "What is your" add nothing on a phone.
* Use a noun, not a question, wherever the answer is obvious from the options.
* Move detail into the field's help text or an option description rather than the label.
* Put shared context in the screen heading instead of repeating it in every label.
## When the question genuinely needs to be long
Some questions cannot be shortened without changing what you are asking. A qualification question, a consent question or anything with a legal wording requirement needs its full text.
For these, put the question above the field and keep the field label minimal:
In the HubSpot form editor, drag a rich text element into position and enter the full question.
Place the dropdown, radio group or text field directly below it.
A single full stop works. The question is already above it, so the label is doing no work.
Alternate rich text and field down the form so the pattern stays consistent.
The result reads as a question with an answer control underneath, which is what customers expect, and it renders identically on every device because the rich text has no length constraint.
Use this pattern only where you need it. Every rich text element is an extra component, and a screen holds a maximum of 50. On very large forms Flowella keeps every input and drops rich text blocks from the end of the screen to stay under Meta's ceiling, so some question copy may not appear on-screen. Mixing the pattern into a form where most labels are already short also makes the layout look uneven.
If you already have HubSpot forms using this pattern, **re-sync** them from the [Forms detail page](/app/forms#form-detail) to publish the rich text copy to Meta. Sync runs before this change only picked up field labels, so the question copy was missing from the Flow.
## How many questions to ask
Completion drops sharply as forms get longer, and WhatsApp is a more impatient surface than a web page.
* **Three or four questions per form** is a good target for a first touch. Ask the rest later in the conversation.
* **One task per screen.** If you are collecting an address and a delivery preference, use two screens.
* **Ten options per screen at most.** More than that and customers stop reading and start guessing.
* **Split long forms in two.** A short qualifying form followed by a conditional second form usually beats one long one, and it lets you branch on the first answer.
See [Lead capture and qualification](/hubspot/workflows/lead-capture-qualify) for a worked example of the two-form pattern.
## Before you sync
Count the characters on your dropdown and text field labels. Anything over 20 is at risk.
Any dropdown with fewer than eight options is a candidate for radio buttons.
From the [Forms](/app/forms) detail page, sync the Flow and open it in Meta Business Suite. The Flow builder preview flags labels that are likely to be shortened.
The builder preview is a guide. A handset is the only true test, and iPhone is the strictest one.
Controls render differently on a laptop. See [WhatsApp Web and Desktop](/app/whatsapp-web-desktop).
## Related
Sync your HubSpot forms to WhatsApp Flows and check their status.
How Flows render when customers reply from a laptop.
End-to-end recipes that put these patterns to work.
Diagnose forms that will not sync or submissions that never arrive.
Meta publishes the underlying constraints in its own documentation. For the full component reference, see [WhatsApp Flows components](https://developers.facebook.com/documentation/business-messaging/whatsapp/flows/guides/components), and for Meta's design guidance see [Flows best practices](https://developers.facebook.com/documentation/business-messaging/whatsapp/flows/guides/bestpractices).
# Forms page: sync HubSpot forms to WhatsApp Flows
Source: https://knowledge.flowella.io/app/forms
Browse the HubSpot forms Flowella tracks, check each WhatsApp Flow's sync status with Meta, and trigger a sync run from the in-app Forms screen.
![Flowella forms synced from HubSpot]()
The Forms page shows every HubSpot form Flowella is tracking for your organisation, the WhatsApp Flow Flowella has built from each one, and whether that Flow is in sync with Meta.
For how to set up the HubSpot integration in the first place, see [HubSpot setup](/hubspot/setup). This page covers the in-app **Forms** screen, not the integration setup.
## How to open it
Go to **Forms** in the left navigation, or:
```text theme={null}
/{org}/forms
```
You can also open Forms scoped to a specific channel at `/{org}/{waba}/{phone}/forms`. The list is the same — the channel scoping is used when you sync a Flow to Meta.
## What the list shows
Each row represents one HubSpot form. Columns include:
* **Form name** and a truncated HubSpot form ID with a one-click copy button.
* **Field count** — how many fields the form has, with a flag if any are unsupported.
* **Last modified in HubSpot** — pulled from HubSpot's own `updatedAt` so you can tell when the form definition itself changed.
* **Catalog updated** — when Flowella last refreshed the form definition from HubSpot.
* **WhatsApp Flow status** — synced, draft, or stale (HubSpot has changed since the last sync).
* **Create WhatsApp Flow / Sync WhatsApp Flow** — the primary action. The label switches to **Sync** when a Flow already exists and to **Stale — Sync needed** when the HubSpot form has been edited since the last sync.
The button is **pre-disabled** with a tooltip when it can't run — for example: HubSpot not connected, no active WhatsApp channel, billing inactive, or the form contains unsupported field types. The tooltip explains exactly which prerequisite is missing.
If your HubSpot account has no forms synced yet, Flowella **bootstraps the catalog automatically** on first visit, so you don't have to trigger an initial pull.
You can filter and search the list to find a specific form quickly. You can also sort it by **Name**, **Added to Flowella**, **Modified in HubSpot**, or **Flow last synced**, in ascending or descending order. The default sort is **Added to Flowella**, newest first. Forms without a date for the chosen sort appear at the end of the list.
## Form detail
Click a row to open its detail page. The detail header shows the same **Create / Sync WhatsApp Flow** primary action as the list row, so you don't have to go back to make changes. From the detail page you can:
* Review the field-by-field mapping between the HubSpot form and the WhatsApp Flow.
* See past **sync runs** — when each was started, status (queued, running, succeeded, failed), and any errors Meta returned.
* Trigger a new sync, **retry** a failed run, or **cancel** a sync that is still in progress.
* Open the corresponding Flow in Meta Business Suite.
## Syncing a form to a WhatsApp Flow
When you click **Create WhatsApp Flow** or **Sync WhatsApp Flow**, Flowella:
1. Runs a **preflight check** — confirms HubSpot is connected, the active channel is verified, the form has at least one supported field, and billing is active.
2. Reads the latest form definition from HubSpot.
3. Generates the equivalent WhatsApp Flow JSON.
4. Uploads it to Meta on the channel you have selected (channel-scoped).
5. Records the sync run on the detail page.
Most syncs take a few seconds. If Meta rejects the Flow, the failure reason appears in the run row as a **user-safe error message** (translated from Meta Graph) — usually because of an unsupported field type, a verification problem on the channel, or a category mismatch. Retry from the same row once you've fixed the cause.
## Channel scope gating
Forms are **org-wide in the list** but **channel-scoped when you sync** — a Flow has to be uploaded against a specific WABA + phone number combination.
| URL you open | What happens |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/{org}/forms` | Lists every form Flowella tracks. If exactly **one** WhatsApp channel is connected, Flowella uses it automatically when you sync. With more than one channel, you need to open Forms in a channel scope before syncing. |
| `/{org}/{waba}/{phone}/forms` | Same list, but syncs target this channel directly. The page **waits for the channel id in the URL to be resolved** before running its HubSpot queries, so you don't see a skeleton flash with results from the wrong channel when the session-cached channel is stale. |
If you click **Sync** from the org-wide URL and Flowella can't decide which channel to use (no channels connected, multiple channels with no scope set, or a stale cross-org session), the button stays pre-disabled with a tooltip explaining what's missing. Switch into the correct channel from the [channel switcher](/essentials/multi-channel#switching-channels), or open `/{org}/{waba}/{phone}/forms` directly.
## Sync error UX
When a sync fails, Flowella turns the run row into a single outline action button so you can fix forwards from the same row:
| Run state | Button | What it does |
| ---------------- | ------------- | ------------------------------------------------------------------------ |
| Failed | **Try again** | Re-enqueues the same form sync. |
| Queued / running | **Cancel** | Best-effort removes the job and marks the run **`FLOW_SYNC_CANCELLED`**. |
| Never synced | **Create** | Runs the first sync for this form. |
The row also carries a **user-safe error badge**:
* **`FLOW_SYNC_PREFLIGHT` + Meta error `#133010`** (phone not registered) — the badge shows the stored Meta message and a **phone-registration** hint, not a generic "not ready". Finish phone registration in **Settings → Meta** and retry.
* **`QUEUE_FAILED`** — the sync queue couldn't pick up the job. Usually transient; retry. If it persists, the platform status page is the next place to check (see [Status & incidents](/essentials/status-and-incidents)).
* **Meta `validation_errors`** — the badge summarises which fields Meta rejected, so you can adjust the HubSpot form (or the field mapping) and retry without leaving the row.
Run history is preserved across retries, so you can see how many attempts a form has taken and what changed between them.
## Flow submissions attach to the enrolled HubSpot contact
When a WhatsApp Flow is sent from a HubSpot workflow, Flowella now passes the enrolled HubSpot contact id through the Flow and includes it as `hs_object_id` when the submission is written back to HubSpot. This makes the submission attach to the **exact contact that HubSpot enrolled** — not a lookalike record — even when the phone number matches multiple contacts, and it removes the last case where the HubSpot phone lookup could fall back to the wrong record.
If your organisation already has published Flows, **re-sync each Flow once** so the new hidden field is included in the Flow JSON uploaded to Meta:
Go to **Forms** and open any form whose WhatsApp Flow was created before this change.
Click **Sync WhatsApp Flow** on the row (or the primary action on the detail page). Flowella re-uploads the Flow JSON to Meta with the hidden contact id field.
Only forms sent from HubSpot workflows need this. Forms sent outside a workflow context are unaffected.
Flows created or synced after the fix already include the field, so no action is needed for new Flows.
## Question copy in rich text blocks
HubSpot lets you place a **rich text element** above a field group so the question text sits above the input rather than inside the field label. Flowella maps those blocks into the WhatsApp Flow alongside the inputs:
| HubSpot rich text | Flow component |
| ----------------------------------- | ---------------------------- |
| `H1` heading | Text heading |
| `H2` or `H3` heading | Text subheading |
| Paragraph, list, or other body copy | Text body (markdown enabled) |
The rich text appears **before** the inputs in the field group, so customers see the question, then answer it. Field labels are still shown in-app, so keep them short — see [Form design best practices](/app/form-design-best-practices).
If you already have HubSpot forms that use rich text above field groups, **re-sync** them from the [form detail page](#form-detail). Older sync runs only picked up field labels, so the rich text question copy was missing from the published Flow until you sync again.
A WhatsApp Flow screen can hold at most **50 components**. On very large forms, Flowella keeps every input and drops rich text blocks from the end of the screen to stay under the ceiling — inputs are never removed, but some question copy may not appear. Split the form across screens (or into two forms) if you need every piece of copy to render.
### Thank-you screen formatting
The same HTML → Flow component mapping now applies to the **thank-you copy** on a HubSpot form. Headings, bold text, non-breaking spaces, and bullet lists survive the sync instead of being stripped to plain text, and the **Done** footer is preserved.
| HubSpot thank-you rich text | Flow component |
| ----------------------------------- | ---------------------------- |
| `H1` heading | Text heading |
| `H2` or `H3` heading | Text subheading |
| Paragraph, list, or other body copy | Text body (markdown enabled) |
Each bullet renders as a single line, so pretty-printed HubSpot markup (a `` nested inside each `
`) no longer produces orphan bullet rows on WhatsApp. Headings over 80 characters still fall back to body text, the same as elsewhere in the Flow.
If a form was synced before this change, its Flow still carries the plain-text thank-you copy. Open the [form detail page](#form-detail) and re-sync to pick up the new formatting.
## Sample data
If you have no HubSpot connection yet, the Forms page renders with **illustrative rows** behind a "Sample data" callout. Connect HubSpot to switch to your real forms.
HubSpot forms with unsupported field types (file upload, signature) cannot be synced as-is. Adjust the form in HubSpot or skip those fields in the WhatsApp Flow.
A form can sync perfectly and still read badly on a phone. Long field labels are shortened on screen, most noticeably on iPhone, and the wrong question type makes it worse. See [Form design best practices](/app/form-design-best-practices) before you build a form.
## Related
Connect the portal Flowella reads forms from.
Build HubSpot forms that render cleanly on every device.
Trigger Flows from a HubSpot workflow.
End-to-end recipes that combine forms, templates, and workflows.
Diagnose form sync issues and missing submissions.
Forms are synced per channel — understand the scoping.
How form submissions are encrypted in transit and at rest.
# Using the Flowella Inbox for WhatsApp Conversations
Source: https://knowledge.flowella.io/app/inbox
Triage WhatsApp conversations with Open/Unseen/Closed and All/Pending tabs, Smart Reply, typing indicators, read receipts, and template sends.
![Flowella inbox with an open conversation]()
The Inbox is where you and your team handle every WhatsApp conversation Flowella is managing. From here you read and reply to messages, send templates when the 24-hour customer service window has closed, see when contacts open and respond to your messages, and keep your queue tidy with tabs and archiving.
## Opening the inbox
1. Sign in to Flowella.
2. In the left navigation, click **Inbox**.
You'll see three areas:
* **Conversation list** on the left
* **Current conversation** in the middle
* **Contact status and actions** on the right of the header
To test a template before using it with real contacts, use **Templates → select a template → Send tab → Test Template** — not the inbox.
## Conversation list
The left-hand panel shows every conversation Flowella is tracking on the active WhatsApp channel.
### Tabs
The list is split into two sets of tabs:
**Status tabs**
* **Open** — conversations that are currently active (not archived).
* **Unseen** — conversations with at least one message your team hasn't acknowledged. The unseen state is **org-wide**: once any teammate opens the conversation, it leaves Unseen for everyone.
* **Closed** — conversations you have soft-closed from the thread. Closed threads stay searchable and can be reopened; they do not appear under **Open**, **Unseen**, or **Pending**.
**Activity tabs**
* **All** — every conversation under the current status tab.
* **Pending** — only conversations **awaiting your reply** (the most recent message was from the customer).
Switching tabs filters the list immediately. Selecting a thread marks it as seen for the whole organization.
### Closing and reopening a conversation
Closing a thread from the conversation view moves it out of **Open** (so it also leaves **All** and **Pending**) and into the **Closed** tab. If the closed thread was the one selected, Flowella clears the middle panel so it's obvious the thread has left the current list.
Reopening a thread from the **Closed** tab flips its status back to Open, so it reappears under **All** (and under **Pending** if the customer's message is still the most recent). Use **Closed** as your list of resolved conversations you might need to revisit; use **Archive** to hide a resolved conversation from **Open** without changing its status.
A screenshot of the new **Closed** tab in the conversation list would be useful here.
Most teams work the **Unseen → Pending** combination first thing in the morning to surface only conversations that still need a human response.
### Conversation items
Each row shows:
* Contact **name** (or phone number if no name is available)
* Latest **message preview**
* **Time** of the most recent message
* An **unread badge** when there are unseen messages
### Search
Use **Search conversations…** to find a contact by name, phone number, or text from a recent message.
### Archive
The **Archive** action moves a resolved conversation out of the **Open** view without deleting it. Archived conversations remain searchable and can be reopened at any time.
## Conversation view
Click any item in the list to open it. The middle panel shows the full message history with that contact, including:
* Incoming messages from the customer (with **read receipts** when WhatsApp reports the customer has read your reply)
* Outgoing messages sent by workflows, templates, or agents — with structured **template cards** (header, body, footer, buttons, media, location) and **Flow answer rows** for Flow submissions, instead of just the template name
* **Typing bubble** when the customer is composing a reply (when Meta surfaces the signal)
* Timestamps for each message
### Starting a new conversation (New message)
Use **New message** at the top of the conversation list to start a WhatsApp thread with a contact who has never messaged you. Enter the contact's name and full international phone number, then click **Open conversation**.
Because WhatsApp only allows free-form messages once the customer has messaged you, a brand-new thread has no session open. Flowella reflects that in three ways:
* The new thread is **not added to the conversation list**, dashboard recent activity, or the v1 conversations list API until it has at least one message. This keeps empty shells out of your team's inbox.
* A toast prompts you to **send a template to start the conversation**. Empty chats that never send a first message are cleaned up automatically after a short grace period.
* The thread body shows a **Send a template to start this chat** CTA in place of the message list. Clicking it opens the template picker so you can pick an approved template and send it as the first message.
Once the template send succeeds, the conversation appears in the list under **All** (and under **Pending** once the customer replies).
A screenshot of the empty new-message conversation with the **Send a template to start this chat** CTA would be useful here.
### Live typing indicator (composer → customer)
When you start typing in the reply composer, Flowella sends a throttled typing indicator to the customer's WhatsApp client. The signal refreshes every \~20 seconds while your draft is non-empty and clears as soon as you send or empty the composer.
This works automatically — there's nothing to enable. It uses Meta's WhatsApp Cloud API typing-indicator endpoint and is only sent inside the 24-hour customer service window.
## The 24-hour customer service window
WhatsApp Business Platform only allows **free-form messages** for 24 hours after the customer's last message. After that, you must use an **approved template**.
Flowella surfaces this state clearly in the composer:
* **Window open** — the composer shows a single text field. Press Enter to send.
* **Window closed** — the composer splits into two tabs: **Reply** (default) and **Send template**, and adds a one-tap **Re-engage** action.
The header of any open conversation also shows the contact's WhatsApp number and their opt-in status.
### Live countdown in the thread header
The open thread's header shows a live **24-hour window countdown** driven off the customer's most recent inbound message. It ticks every second and adapts its format and tone as time runs low:
* **Green (open)** — more than an hour left; shows `Xh YYm` (for example, `22h 34m`).
* **Amber (warning)** — under an hour left; shows `Mm SSs` (for example, `34m 12s`).
* **Red (closed)** — the window has expired; shows **Session closed**.
Hover the countdown to see the exact **closes-at** time in your local timezone. When the timer flips from open to closed (or the customer sends a new inbound), the composer automatically switches between free-text and re-engage modes on the next tick — you don't need to reload the thread.
## Reply tab (Smart Reply)
The **Reply** tab lets you type a free-text message **even when the 24-hour window has closed**. Flowella does this by wrapping your text into an approved **reopen template** (one of three system templates: **Service**, **Update**, or **Offer**).
* Inside the window — your text sends as a normal free-form WhatsApp message.
* Outside the window — your text is placed into variable `{{3}}` of the active reopen template. Variable `{{1}}` is the contact's first name and `{{2}}` is your business name; both are filled automatically.
A banner above the composer explains that an out-of-window send uses Utility template pricing (Meta charges per conversation; see [Pricing and conversation categories](/account/pricing-and-conversation-categories)).
Reply templates are provisioned automatically the first time you open the Inbox on a Meta-connected channel, and an hourly worker backfills anything still missing. You can edit the framing text under [Reply templates](/settings/reply-templates).
### One-tap Re-engage on a closed window
When the window is closed, the composer surfaces a one-tap **Re-engage** button next to the send action. Clicking it sends the org's default **Service** re-engagement template (`flowella_reopen_service`) immediately — no free text required. Use it to reopen a conversation you don't have a bespoke reply for yet, then continue the thread inside the fresh 24-hour window.
* The CTA always uses the **Service** kind, which is the system-managed default. Update the framing copy under [Reply templates](/settings/reply-templates).
* Standard opt-out and Smart Reply checks still apply — the CTA is hidden or disabled when the contact isn't eligible.
* One tap = one send. The button disables while the send is in flight to prevent duplicates.
### First closed-window education
The first time an agent in your organization lands on a **closed** window in the Inbox, Flowella shows a one-time explainer dialog covering what re-engagement templates are, why the composer switches modes, and how the Utility conversation charge works. Dismissing the dialog is remembered per organization in the browser's local storage, so it won't appear again for that agent.
## Send template tab
Use **Send template** when you want to pick a specific approved template rather than wrap a free-text reply.
1. Pick a **WhatsApp template** from the list.
2. Fill any required variables (the contact's saved values prefill where possible).
3. Click **Send**.
Template messages are commonly used to:
* Reopen a conversation with structured content (appointment reminder, order update)
* Send notifications, confirmations, or reminders
* Start a structured WhatsApp Flow from the inbox
## Failed message bubbles
When a template or free-form send is rejected by Meta after Flowella has already dispatched it, the outgoing bubble in the thread renders in a failed state with a **plain-English reason** underneath — not a raw Meta error code. The same wording appears in the **Details** column on **Templates → Statistics** and in the [Analytics per-template drill-down](/app/analytics#per-template-drill-down), so agents and admins see the same explanation.
The mapping covers the most common Meta delivery-failure codes:
| Meta code | What agents see under the failed bubble |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **131049** | Marketing message not delivered because the recipient is currently receiving fewer promotional messages — a per-user WhatsApp cap. Switch the template to Utility, or wait for the contact to message you first. See [Healthy ecosystem engagement](/troubleshooting/healthy-ecosystem-engagement). |
| **131050** | Contact has opted out of marketing messages from your business. Do not retry marketing templates. |
| **131048** | Send blocked because of a spam or quality signal on your WhatsApp Business number. Review your [quality rating](/meta/quality-score) before sending again. |
| **131063** | Marketing template sends are disabled for this WhatsApp Cloud API configuration. Check marketing settings in Meta Business Manager. |
| **131064** | WhatsApp limited this send because of template category or classification issues. Review the template's category against Meta's [marketing vs utility rules](/app/template-reference). |
Other Meta failures fall back to Meta's own wording (with the code in parentheses) so nothing is hidden.
For the underlying Meta reference, see [Meta's WhatsApp Cloud API error codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
## Contact status and opt-outs
The conversation header shows the contact's WhatsApp number and their opt-in status:
* **Opted in** — Flowella is allowed to send messages.
* **Opt out** button — mark the contact as opted out if they ask to stop.
When a contact is opted out, Flowella will not send any further messages to them, even if a workflow or flow attempts to do so.
## Recommended agent workflow
Open the **Inbox**, switch to the **Unseen** tab, then the **Pending** activity tab. You'll see only conversations awaiting a human reply.
Reply to conversations from oldest to newest while still inside the 24-hour window where possible.
If 24 hours have passed since the customer's last message, type into the **Reply** tab to send a Smart Reply, or pick a specific template from **Send template**.
If a contact asks to stop receiving WhatsApp messages, click **Opt Out** in the conversation header.
Once a conversation is resolved, close it to move it into the **Closed** tab (still searchable and reopenable), or archive it to hide it from **Open** without changing status.
## Limitations
* The inbox is designed for **one-to-one conversations**. For bulk sends, see [Templates](/app/templates) and [Campaigns overview](/campaigns/overview).
* Free-form replies are only possible inside WhatsApp's **24-hour customer service window**. After that, **Reply** uses a reopen template and **Send template** uses any approved template.
* If a template send fails, check that:
* The contact's number is in full [international format](/hubspot/phone-number-format).
* The contact is [opted in](/app/opt-outs).
* The template is approved on your WhatsApp Business account — see [Templates](/app/templates) and [Template rejected](/troubleshooting/template-rejected).
## Related
Edit the Service, Update, and Offer reopen templates used by the Reply tab.
Create and submit templates for sending outside the 24-hour window.
Manage consent for the contacts you message.
Diagnose sends that don't reach the recipient.
# Media in WhatsApp template headers: images and videos
Source: https://knowledge.flowella.io/app/media-in-template-headers
What media formats and sizes WhatsApp accepts in template headers, why YouTube links don't embed, and how to upload and reference media via Flowella.
A WhatsApp template can carry one piece of media in its header: an image, a video, or a document. Used well, it doubles the open and engagement rates of an otherwise text-only message. Used badly — wrong format, broken URL, mismatched MIME type — it causes the send to fail or the template to look amateurish.
This page is the practical reference for what works, what doesn't, and how to plumb the media through Flowella.
## Supported formats and limits
These are the formats and size limits Meta enforces on media in template headers (and elsewhere in WhatsApp Business Platform messages).
### Images
| Format | Extension | MIME type | Max size |
| ------ | ---------------- | ------------ | -------- |
| JPEG | `.jpeg` / `.jpg` | `image/jpeg` | 5 MB |
| PNG | `.png` | `image/png` | 5 MB |
Images must be **8-bit, RGB or RGBA**. WebP is **not** accepted in template headers (it's only valid in sticker messages, which are a separate message type).
**Recommended dimensions:** 1.91:1 aspect ratio, minimum 800×418 px. Square (1:1) images also render acceptably. Other aspect ratios are letterboxed by the WhatsApp client.
### Videos
| Format | Extension | MIME type | Max size |
| ------ | --------- | ------------ | -------- |
| 3GPP | `.3gp` | `video/3gpp` | 16 MB |
| MP4 | `.mp4` | `video/mp4` | 16 MB |
Videos must use the **H.264 video codec** and **AAC audio codec**, with a **single audio stream or no audio**.
Videos encoded with the H.264 **"High" profile and B-frames** are not supported by Android WhatsApp clients. Encode (or re-encode) with the H.264 **"Main" profile without B-frames**, or the **"Baseline" profile**, and place `moov` boxes before `mdat` boxes for broader compatibility.
If using ffmpeg, the `-movflags faststart` flag handles the `moov`/`mdat` ordering.
### Documents
| Format | Extension | MIME type | Max size |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | -------- |
| PDF | `.pdf` | `application/pdf` | 100 MB |
| Microsoft Word | `.doc` / `.docx` | `application/msword` / `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | 100 MB |
| Microsoft Excel | `.xls` / `.xlsx` | `application/vnd.ms-excel` / `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | 100 MB |
| Microsoft PowerPoint | `.ppt` / `.pptx` | `application/vnd.ms-powerpoint` / `application/vnd.openxmlformats-officedocument.presentationml.presentation` | 100 MB |
| Plain text | `.txt` | `text/plain` | 100 MB |
PDFs are the most reliably rendered across devices. Office documents work but require the recipient to have a compatible app installed; on a non-business mobile they usually open as previews.
## What doesn't work
You cannot embed a YouTube or Vimeo video in a template header. The header has to be an MP4 or 3GPP file that Meta can fetch and host.
If you want to send a YouTube video, two options:
1. **Put the YouTube link in the body or a URL button.** Tapping it opens the YouTube app or browser. The video preview shown in WhatsApp will be a static thumbnail.
2. **Download the video and re-upload it as MP4.** Subject to your rights to redistribute the content, which usually means it has to be your own video.
The latter is the way to get an actual in-conversation video preview.
Animated GIFs (`.gif`) are not in the supported list. WhatsApp converts them server-side when shared peer-to-peer in the consumer app, but the Business Platform does not. Re-encode the GIF as an MP4 (which WhatsApp's mobile clients play with auto-play and no sound, the same way they show a GIF).
WebP images are only valid for sticker messages, not template headers. Convert to JPEG or PNG before using as a header image.
iPhones default to saving photos in HEIC format, which is not on the supported list. Either change the iPhone setting to capture in JPEG, or convert HEIC to JPEG before upload.
A 6 MB image, an 18 MB video, or a 110 MB PDF will be rejected. Compress before upload. For images, the WhatsApp client also re-compresses on display, so a 4 MB photo isn't going to look meaningfully better than a 1 MB one on a phone screen.
## Two ways to attach media to a template
Meta supports two patterns for getting media into a template:
### Pattern 1: Media handle (recommended)
Upload the file via Meta's Media API, get back a **media handle**, and reference the handle when you send the template. Used by Flowella by default.
Benefits:
* Meta hosts the file, so there are no broken-URL failures at send time.
* Faster delivery because Meta doesn't have to fetch from an external URL.
* Works for the full size limits above.
The handle is valid for 30 days. If your template is going out repeatedly with the same media, Flowella refreshes the handle automatically before it expires. For DOCUMENT headers, Flowella also reuses recently uploaded document media where possible, so re-sends of the same template don't need to re-upload the file. If Meta rejects a reused id, Flowella falls back to uploading again.
### Pattern 2: Public HTTPS URL
Provide a URL to a publicly accessible file. Meta fetches it at send time.
This is useful when:
* The media changes per recipient (a personalised PDF, a per-order shipping label).
* The media is generated on the fly and you don't want to upload-per-send.
Caveats:
* The URL must be **publicly reachable** (no auth) and use **HTTPS with a valid certificate**.
* If the URL returns an error or is slow, the send fails.
* Meta caches the fetched file for a while; updating the file at the URL doesn't necessarily refresh what gets sent.
## How Flowella handles media upload
For most use cases, Flowella manages the media handle for you:
In **Templates → Create**, choose **Image**, **Video**, or **Document** as the header type, then drag the file into the upload area. For **Document** headers, the editor also shows a **Document filename** field that defaults from the uploaded file — edit it to control the name recipients see on the WhatsApp document bubble.
Format, size, and MIME type are checked before submission. If the file is unsupported, you see an error immediately rather than waiting for Meta to reject the template.
The file is uploaded via Meta's Media API. The returned handle is saved against the template.
When the template is submitted for approval, Meta sees the actual media (not a URL), so the review process can evaluate the visuals as part of approval.
Until the template's header media changes, every send uses the same handle. Handles are automatically refreshed before expiry. For DOCUMENT headers, the **Document filename** you set in the editor is persisted with the draft, carried through Meta's approval, and used on every send.
When you use **Templates → Duplicate**, Flowella copies the header file and the **Document filename** into the new draft. If the copy fails, the editor shows a warning and blocks publishing until you re-upload the file.
For per-recipient media (personalised PDFs, shipping labels), use the **Public URL** option in the template builder and pass the URL as a variable when triggering the send from a workflow or the API. See [Workflow Actions](/hubspot/workflow-actions).
## Designing for the WhatsApp viewport
A few design notes that don't appear in Meta's spec but matter in practice:
* **Text on images.** Keep it large and high-contrast. WhatsApp shows the image at roughly mobile-screen width, so anything smaller than about 14 px renders unreadable.
* **Safe area.** WhatsApp may crop or letterbox; keep critical content in the centre 80% of the image.
* **Brand consistency.** The header image and the WhatsApp display name and profile photo all sit close together — keep them visually consistent.
* **First frame of a video.** WhatsApp uses the first frame as the still preview before the video plays. Don't open with a black frame or a corporate logo splash; start on a meaningful image.
* **Document filename.** When sending a PDF or other document, the **filename** is visible to the recipient on the WhatsApp document bubble. The template editor exposes a **Document filename** field under the DOCUMENT header upload; it defaults from the uploaded file's name and is what recipients actually see when the template is sent. Use a clear, descriptive name like `Acme-Order-12345-Receipt.pdf`, not `attachment.pdf` or the Meta CDN object name.
## Common errors and fixes
The file's actual MIME type doesn't match what was declared. Often happens when an iPhone-exported "JPEG" is actually HEIC, or when a tool renames a `.docx` to `.pdf` without converting.
Fix: inspect the file (on macOS/Linux: `file -I yourfile.png`) and either re-export in the right format or change the extension to match.
The audio codec is something other than AAC, or there are multiple audio streams.
Fix: re-encode with `ffmpeg -i input.mp4 -c:v libx264 -profile:v main -c:a aac -movflags faststart output.mp4`.
Encoded with H.264 High profile and B-frames. Re-encode with Main or Baseline profile.
Meta can't reach the URL. Common causes: the URL requires authentication, the certificate is invalid, the server is slow to respond (timeout), or the URL returns a redirect instead of the file.
Fix: test the URL with `curl -I` to confirm it returns 200 with the right content type, and that the certificate validates. Then re-try.
The source is low-resolution, or it's been upscaled. WhatsApp doesn't re-process for sharpness; what you upload is what gets shown.
Fix: upload at least 800 px on the long edge for a 1.91:1 image, and don't upscale a small source.
## Related guides
* [Template reference](/app/template-reference) — the full template structure that this media slots into
* [Templates](/app/templates) — step-by-step template creation in Flowella
* [Workflow Actions](/hubspot/workflow-actions) — passing per-recipient media URLs through HubSpot workflows
# Notification events
Source: https://knowledge.flowella.io/app/notification-events
The full catalogue of in-app and email notifications Flowella sends, grouped by category, with delivery channels and whether they can be unsubscribed.
Flowella sends notifications when something important happens in your workspace — a template gets approved, you're approaching a usage threshold, a HubSpot sync fails, or a teammate accepts an invite. This page catalogues every event Flowella can emit, where it shows up, and how to manage your preferences.
For the in-app notifications feed itself, see [Notifications](/app/notifications). For notification preferences UI, see [Settings → Notification preferences](/settings/notification-preferences).
## How notifications are delivered
Notifications can land in up to three places:
| Channel | Where it appears | Customisable |
| --------------------- | ----------------------------------------------- | ------------------------------ |
| **In-app feed** | Bell icon, top right — `/notifications` | Per category (most events) |
| **Email** | The email address on your Flowella user profile | Per category (most events) |
| **Operational email** | The org's billing email | Always on for billing/security |
Each event below shows which channels deliver it by default.
## Event catalogue
### Account & authentication
| Event key | Description | Channels | Optional? |
| --------------------------- | ------------------------------------------------------------------------------------------------ | -------------- | ------------------ |
| `WELCOME` | Sent immediately after you register a Flowella account. Confirms signup and links to onboarding. | In-app + email | No |
| `AUTH_PASSWORD_CHANGED` | Your password was changed. | In-app + email | **No — mandatory** |
| `AUTH_MAGIC_LINK_REQUESTED` | A magic-link sign-in was requested for your account. | Email only | **No — mandatory** |
| `AUTH_NEW_DEVICE` | A new device or location signed in. | In-app + email | **No — mandatory** |
| `ORG_INVITE_ACCEPTED` | Someone you invited accepted and joined the org. | In-app | Yes |
Authentication and security events cannot be unsubscribed from. This is enforced server-side regardless of your notification preferences.
### Billing & usage
| Event key | Description | Channels | Optional? |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------- | --------------------- |
| `BILLING_SUBSCRIPTION_STARTED` | A new subscription was activated for the org. | In-app + operational email | Operational always on |
| `BILLING_SUBSCRIPTION_CHANGED` | Plan was upgraded or downgraded. | In-app + operational email | Operational always on |
| `BILLING_PAYMENT_FAILED` | Stripe could not charge the card on file. | In-app + operational email | Operational always on |
| `BILLING_PAYMENT_RECOVERED` | A failed payment succeeded on retry. | In-app + operational email | Operational always on |
| `BILLING_SUBSCRIPTION_CANCELLED` | The subscription has been cancelled and will end at the period close. | In-app + operational email | Operational always on |
| `BILLING_TRIAL_STARTED` | The 14-day free trial was provisioned at signup. | In-app + email | Yes |
| `BILLING_TRIAL_ENDING` | The 14-day trial ends in less than 72 hours. | In-app + email | Yes |
| `BILLING_TRIAL_EXPIRED` | The trial window has closed. | In-app + operational email | Operational always on |
| `USAGE_SOFT_50` | You have used 50% of your plan's monthly conversation allowance (or your trial's 5,000-message cap). | In-app + email | Yes |
| `USAGE_SOFT_80` | You have used 80% of your plan's monthly allowance. | In-app + email | Yes |
| `USAGE_HARD_100` | You have used 100% of your plan's monthly allowance — overage applies (or, on trial, sends are now blocked). | In-app + operational email | Operational always on |
### Templates
| Event key | Description | Channels | Optional? |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------- |
| `TEMPLATE_SUBMITTED` | A template was submitted to Meta for approval. | In-app | Yes |
| `TEMPLATE_APPROVED` | Meta approved a template. | In-app + email | Yes |
| `TEMPLATE_REJECTED` | Meta rejected a template. The notification includes Meta's rejection reason. | In-app + email | Yes |
| `TEMPLATE_FLAGGED` | Meta paused a template due to quality issues. | In-app + email | Yes |
| `TEMPLATE_PAUSED` | Meta transitioned a template into `PAUSED`. Sends from journeys, campaigns, and HubSpot actions using it are blocked until Meta restores it. Surfaces as the **Paused by WhatsApp** pill on the templates list. | In-app + email | Yes |
| `TEMPLATE_DISABLED` | Meta transitioned a template into `DISABLED`. The template must be updated or replaced before sending again. Surfaces as the **Disabled by WhatsApp** pill on the templates list. | In-app + email | Yes |
| `TEMPLATE_QUALITY` | Meta's quality score for a template dropped to `RED`. Surfaces as the **Quality: Red** pill on the templates list. | In-app + email | Yes |
| `TEMPLATE_CATEGORY_CHANGED` | Meta re-categorised a template (for example, Marketing → Utility). | In-app + email | Yes |
### WhatsApp Flows & forms
| Event key | Description | Channels | Optional? |
| --------------------- | ------------------------------------------------------------------------- | -------------- | --------- |
| `FLOW_SYNC_SUCCEEDED` | A HubSpot form was successfully synced to a WhatsApp Flow. | In-app | Yes |
| `FLOW_SYNC_FAILED` | A sync run failed. The notification includes the user-safe error message. | In-app + email | Yes |
| `FLOW_PUBLISHED` | A Flow was published to Meta. | In-app | Yes |
### HubSpot integration
| Event key | Description | Channels | Optional? |
| ---------------------- | --------------------------------------- | -------------- | --------- |
| `HUBSPOT_CONNECTED` | HubSpot OAuth completed. | In-app | Yes |
| `HUBSPOT_DISCONNECTED` | HubSpot connection was lost or revoked. | In-app + email | Yes |
| `HUBSPOT_SYNC_FAILED` | A scheduled HubSpot sync run failed. | In-app + email | Yes |
### Channels & Meta
| Event key | Description | Channels | Optional? |
| ----------------------------- | ----------------------------------------------------------- | -------------- | --------- |
| `CHANNEL_CONNECTED` | A new WhatsApp channel was added. | In-app | Yes |
| `META_VERIFICATION_REQUIRED` | The channel needs business verification before it can send. | In-app + email | Yes |
| `META_VERIFICATION_COMPLETED` | Business verification completed. | In-app | Yes |
| `QUALITY_RATING_DROP` | Channel quality rating dropped to **Medium** or **Low**. | In-app + email | Yes |
### Exports & long-running jobs
| Event key | Description | Channels | Optional? |
| ------------------ | ---------------------------------------------------- | -------- | --------- |
| `EXPORT_READY` | A CSV/PDF export you triggered is ready to download. | In-app | Yes |
| `IMPORT_COMPLETED` | A CSV import (for example, opt-outs) finished. | In-app | Yes |
## Operational sweeps
Flowella runs a **daily notification reminders sweep**. If an unread `TEMPLATE_REJECTED`, `HUBSPOT_SYNC_FAILED`, or `BILLING_PAYMENT_FAILED` notification has been sitting for more than 24 hours, the sweep re-surfaces it with an email reminder. This means you can't silently miss a critical event by closing the bell icon.
## Where to manage your preferences
* **Per-user, per-category** — Settings → Notification preferences. Each category above can be toggled for in-app, email, or both, with the exception of mandatory categories (auth, billing operational).
* **Per-org operational email** — Settings → Organisation → Notifications email. This is the recipient for billing, security, and other org-wide operational mails.
If you're not receiving emails you expect, first check Settings → Profile that your email address is verified, then check your spam folder for messages from `notifications@flowella.io`. Unverified emails do not receive notifications.
## Related
Choose which categories deliver in-app, by email, or both.
Read and clear notifications in-app.
Push the same events to your own systems.
Operational events and where to triage when something breaks.
# Notifications
Source: https://knowledge.flowella.io/app/notifications
Read and manage in-app notifications about WhatsApp templates, integrations, exports, and operational events across your Flowella organisation.
![Flowella notifications]()
Notifications are the in-app feed Flowella uses to tell you about things that need your attention or that have just finished — template approvals, failed integrations, completed exports, and operational events affecting your org.
## How to open it
Click the bell icon in the top-right, or go to:
```text theme={null}
/{org}/notifications
```
The bell shows an unread count. Notifications are scoped to your organisation, so every member of the org sees the same feed.
## What appears here
Meta approved or rejected a submission, a template was paused for quality reasons.
HubSpot or Meta needs reconnecting, a webhook is failing.
An analytics export is ready to download.
A payment failed or a subscription state changed.
Incident notices and maintenance windows from Flowella.
See the full catalogue of events Flowella can emit.
The exact event list grows as we ship new features.
## Reading and clearing
* Click a row to open its **detail view** in a modal. The detail view shows the full payload, including links to the related object (template, channel, export, etc.).
* Click **Mark all read** to clear the unread badge for everything in the feed.
* Pagination is at the bottom of the list (20 per page).
Marking a notification read is per-user. Other members of your org keep their own unread state.
## Email and notification settings
Some events are also delivered by email. Configure which categories email you (and which only stay in-app) under [Notification preferences](/settings/notification-preferences).
## Retention
Notifications are kept in the feed long enough for routine review. Expect older notifications to be pruned over time so the feed stays useful — anything time-sensitive is also delivered by email or as a webhook event so you do not lose it. If you need a permanent record of a specific event, capture it from the detail view at the time.
If a teammate keeps missing template approvals, point them at [Notification preferences](/settings/notification-preferences) to enable email for the **Templates** category.
## Related
The full list of events Flowella can emit, with channels and mandatory flags.
Choose which categories deliver in-app, by email, or both.
Operational notifications and where to check platform health.
Push events to your own systems instead of polling the feed.
# Managing WhatsApp Opt-Outs and Consent in Flowella
Source: https://knowledge.flowella.io/app/opt-outs
Track consent, handle automatic keyword opt-outs, view a contact's full consent history, and manually update opt-in status to stay compliant at scale.
![Flowella opt-outs page]()
The Opt-Outs page is where Flowella tracks who has consented to receive WhatsApp messages and who has asked you to stop. Keeping this data accurate means your workflows will not message people who have opted out, and you have an audit trail to support compliance reporting.
## Opening the opt-outs page
1. Log in to Flowella.
2. In the left menu, click **Opt-Outs**.
The page is **scoped to the active WhatsApp channel**. If your org has more than one WhatsApp number, switch channels using the channel picker — the opt-outs list updates to show consent records for that number only.
At the top you will see three summary figures: **Total** contacts, how many are **Opted Out**, and how many are **Opted In**. Below that is a search bar where you can find a specific contact by phone number or name, and a **Refresh** button to pull the latest data.
If the list is empty, Flowella shows a help-oriented empty state with links to add contacts manually, import from CSV, or read more about how consent is captured.
## Adding contacts to your opt-out list
You can add contacts to the opt-out list without waiting for an inbound `STOP` message — useful when consent (or withdrawal of consent) was captured outside WhatsApp.
### Add a single contact manually
On the Opt-Outs page, click **Add contact** (top right).
Type the contact's phone number in international E.164 format (for example, `+447700900123`). Optionally add a display name.
Choose **Opted Out** (default) or **Opted In**. For most manual adds you want Opted Out.
Flowella validates the number, creates the consent record on the active channel, and logs the change as a manual consent event with your user as the source.
### Import contacts from CSV
For bulk updates — for example, importing an existing suppression list when you first connect a channel — use the CSV import dialog.
On the Opt-Outs page, click **Import CSV**.
The dialog offers a downloadable CSV template with the required columns: `phone` (E.164), `name` (optional), and `status` (`opted_in` or `opted_out`, defaults to `opted_out`).
Drag and drop your CSV or pick it from disk. Flowella validates each row and previews how many records will be created, updated, or skipped (for example, invalid phone numbers).
Confirm the import. Each row creates one consent event marked as a CSV import, attributed to your user. Rows that fail validation are downloadable as a separate "errors" CSV so you can fix and re-import.
CSV import is **idempotent**: re-importing the same file does not duplicate events. If a contact already has the same status, the row is skipped.
## Understanding the opt-outs table
The main table lists one row per WhatsApp number Flowella knows about.
| Column | What it shows |
| ------------------ | ------------------------------------------------------------ |
| **Phone Number** | The WhatsApp number in international format. |
| **Name** | The contact name, if known. |
| **Status** | A badge showing **Opted In** or **Opted Out**. |
| **Last Updated** | When the consent status last changed. |
| **Events** | How many consent events have been recorded for this contact. |
| **Actions → View** | Opens the detailed record for that number. |
Use the pagination controls at the bottom to move through the full list.
## Automatic opt-out and opt-in keywords
Flowella automatically updates a contact's status when they send certain keywords in any WhatsApp thread Flowella handles. These keywords follow the HubSpot SMS pattern and are matched case-insensitively.
If a contact sends one of these words on its own, or as the first word of a message, Flowella marks them as **Opted Out**:
| Language | Keywords |
| ---------- | --------------------------------------------------------- |
| English | `STOP`, `STOPALL`, `UNSUBSCRIBE`, `CANCEL`, `END`, `QUIT` |
| Spanish | `ALTO` |
| French | `ARRÊTER` |
| Portuguese | `PARAR` |
| German | `BEENDEN` |
| Japanese | `停止` |
After an automatic opt-out:
* Flowella **blocks all automated WhatsApp sends** (flows, workflows, campaigns) to that number.
* The contact's status shows as **Opted Out** in the Inbox header and on the Opt-Outs page.
* A consent event is logged against that number.
Treat an automatic opt-out as a hard stop for marketing and non-essential messages.
If a contact later wants to hear from you again, they can send an opt-in keyword. When Flowella sees one of these, it sets the contact back to **Opted In** automatically — no agent action required:
| Language | Keywords |
| ---------- | ------------------------------ |
| English | `START`, `SUBSCRIBE`, `UNSTOP` |
| Spanish | `EMPEZAR` |
| French | `COMMENCER` |
| Portuguese | `INICIAR` |
| German | `LOSLEGEN` |
| Japanese | `開始` |
Inbound `START` / `UNSTOP` (and the localised equivalents) flip the contact back to **Opted In** and log a consent event sourced as **inbound keyword**. Subsequent automated sends from workflows, flows, and campaigns will resume on the next trigger.
Make it clear in your message copy that contacts can reply with these words to manage their preferences.
## Viewing a contact's consent history
1. On the Opt-Outs page, find the contact using the search bar — search by name or phone number.
2. Click **View** in the **Actions** column.
The detail view shows:
* The current **status** (Opted In or Opted Out).
* When the status last changed and the mechanism that triggered it (for example, "Automatic keyword: STOP").
* The full **event history**, including automatic opt-outs and opt-ins from keywords, and any manual changes made by your team.
This event history provides an audit trail for compliance and internal reporting.
## Manually updating opt-in status
Sometimes a contact gives or withdraws consent through another channel — by phone, email, or a signed form. When that happens, you can update their status in Flowella manually from two places.
On the **Opt-Outs page**, use the search bar to find the contact by name or phone number.
Click **View** in the **Actions** column to open the contact's detail view.
Use the controls on the detail view to set the status to **Opted In** or **Opted Out** as appropriate.
Save the update. The change is recorded as a new consent event in the contact's history.
You can also update status directly from the **Inbox**: open the conversation, then use the **Opted In / Opt Out** buttons in the conversation header. If a contact explicitly asks to stop WhatsApp messages during a chat, click **Opt Out**. If they later give clear consent again and you have a record of it, switch them back to **Opted In**. Every manual change is logged as a new consent event.
## How Flowella uses opt-out data
Whenever Flowella is about to send a WhatsApp message, it checks the contact's current status:
* If the contact is **Opted Out**, Flowella **blocks the send** for all automated messages.
* If the contact is **Opted In**, the message proceeds as normal, subject to WhatsApp's 24-hour and template rules.
This check applies across:
* HubSpot workflows using the Flowella custom action
* Automated flows and campaigns
* Inbox template sends
Agents can still view conversation history and opt-out status in the Inbox so they can make informed decisions and stay compliant.
## Good practice checklist
Include a line in your messages such as "Reply STOP to opt out" so contacts always know how to unsubscribe.
Review the **Opt-Outs page** regularly to understand consent trends in your contact base.
If you use HubSpot subscription preferences, keep them aligned with Flowella's opt-out status wherever possible.
Train your team to respect the **Opted Out** label and never attempt to bypass it.
## Related
Diagnose cases where an opted-out contact still receives messages.
How HubSpot's Marketing Contacts model intersects with WhatsApp opt-in.
Opt-outs are per-channel — understand the scoping rules.
Audit trail, consent records, and compliance.
# WhatsApp template reference: categories, headers, buttons
Source: https://knowledge.flowella.io/app/template-reference
Reference for WhatsApp template categories, header formats, button types, variable syntax, coupon and location templates, and the submission lifecycle.
This page is a reference for the building blocks of a WhatsApp template — categories, headers, body, buttons, variables, advanced template types, and the submission lifecycle. For the step-by-step of creating and testing a template, see [Templates](/app/templates). For media format limits, see [Media headers](/app/media-in-template-headers).
## Categories
Every template has exactly one category, set when you submit it to Meta. The category drives **pricing** and **what content is allowed**.
| Category | Use it for | Notes |
| ------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Marketing** | Promotions, offers, event invites, re-engagement | Most expensive tier; subject to opt-in rules |
| **Utility** | Order updates, account alerts, reminders, follow-ups to a user-initiated flow | Cheaper than Marketing; content must relate to a specific transaction or request |
| **Authentication** | One-time passwords and account verification codes | Strict format; no marketing content allowed; cheapest tier |
If Meta thinks your template doesn't match the category you picked, it will be **rejected** or **re-categorised** — common with Marketing content submitted as Utility. The category can also change automatically as Meta observes usage patterns, which then changes the rate you're charged.
## Header formats
A template's header is optional. When present, it can be one of:
* **TEXT** — short string, may include one variable.
* **IMAGE** — JPEG or PNG, max 5 MB. See [Media headers](/app/media-in-template-headers).
* **VIDEO** — MP4 or 3GPP with H.264/AAC, max 16 MB.
* **DOCUMENT** — PDF (most reliable), Office formats, or plain text. Max 100 MB. The editor has a **Document filename** field that defaults from the uploaded file; the value you set there is what the recipient sees on the WhatsApp document bubble, so pick something descriptive like `Acme-Order-12345-Receipt.pdf`.
* **LOCATION** — latitude, longitude, name, and address. Useful for store visits or delivery confirmations.
Media headers can be attached either as a **media handle** (uploaded once to Meta) or as a **public HTTPS URL** fetched per send. See [Media headers](/app/media-in-template-headers) for the trade-offs.
## Body and variables
The body is the main message text. Variables use **double curly braces with a 1-based index**:
```text theme={null}
Hi {{1}}, your order {{2}} has shipped. Track it here: {{3}}
```
Rules:
* Numbers must be sequential starting from `{{1}}` — you cannot skip indexes.
* Provide a sample value for every variable when you submit. Meta uses the samples to evaluate the template.
* Keep variables to short, predictable values. Long pasted blocks are a common rejection reason.
The same `{{n}}` syntax is used in **TEXT headers** and **URL buttons** (see below).
### Formatting in the body
WhatsApp supports a limited set of inline formatting in template bodies:
* **Bold** with `*asterisks*`
* **Italic** with `_underscores_`
* **Strikethrough** with `~tildes~`
* **Monospace** with triple-backticks
Use formatting sparingly. Templates with heavy formatting are often rejected as looking spammy.
## Footer
Optional plain text shown after the body. No variables, no formatting.
## Buttons
A template can include up to **10 buttons total**, grouped as either quick replies or call-to-action. The combinations Meta allows have shifted over Cloud API versions; the most reliable patterns:
| Button type | What it does | Example | Variable? |
| ---------------- | ------------------------------------------------- | ------------------------------- | ----------------------------- |
| **QUICK\_REPLY** | Sends a pre-set text reply back to your business | `Yes, that's me` | No |
| **URL** | Opens a web page | `https://acme.com/orders/{{1}}` | One in the URL |
| **PHONE** | Calls a phone number | `+44 20 7946 0000` | No |
| **COPY\_CODE** | Copies a code to the clipboard | `SAVE20` | One for the code |
| **FLOW** | Opens a WhatsApp Flow | (linked Flow ID) | Variables via the Flow itself |
| **CATALOG** | Opens your WhatsApp catalog | (linked catalog ID) | No |
| **MPM** | Multi-Product Message launcher | (catalog products) | No |
| **VOICE\_CALL** | Initiates a WhatsApp voice call (where supported) | (your business number) | No |
Quick reply buttons are useful when you want a structured response (good for analytics). URL and phone buttons are useful for routing recipients off WhatsApp into your stack. FLOW buttons are the gateway into HubSpot-form-driven Flows that Flowella specialises in.
## Specialised template types
Meta has several specialised marketing template types that bundle extra functionality on top of the base structure.
### Carousel templates
A carousel template shows multiple cards in a horizontal scroll, each with its own media, body, and buttons. Useful for catalog showcases, multi-product offers, or feature comparisons.
* **Up to 10 cards** per template.
* Each card has its own image or video header (one media type per template — all images or all videos, not mixed).
* Each card can have up to **2 buttons** (Quick Reply, URL, or Phone).
* The body of each card can have up to 3 variables.
Approval is per-template (not per-card), so all cards must comply with the chosen category.
### Limited-time offer (LTO) templates
LTO templates render a countdown timer beneath the body. Once the timer expires, the offer is shown as expired and tapping the CTA does nothing.
* A **deal code** parameter is required and shown to the user.
* An **expiration epoch (in seconds)** is required.
* The CTA button is usually a Copy Code or URL.
Best for genuine time-limited offers — using LTO for offers that don't actually expire causes user complaints and category re-categorisation away from Marketing.
### Coupon code templates
Like LTO but without the countdown — just a code the user can copy with one tap.
* The code can be **up to 20 characters** (recently increased from 15).
* The Copy Code button copies the value supplied at **send time** — the template's `example` field is a placeholder only and is never sent.
* In **Templates → Send tab** and the **inbox template dialog**, coupon-code templates surface a dedicated **Coupon code buttons** input where you type the codes you actually want to send (one per recipient row for bulk sends). Older "Copy code" / "Copy coupon code buttons" labels have been replaced with this single, consistent term.
### Authentication templates
Specialised templates for OTP delivery. Three sub-types:
* **One-tap autofill** — uses Android's autofill API to populate the OTP automatically when the user taps the button. Best UX where supported.
* **Copy code** — shows a Copy button; user pastes the code into your app. Works everywhere.
* **Zero-tap** — for trusted senders, the OTP can be delivered without any tap (an automatic API callback from the WhatsApp client to your app). Strict eligibility.
Authentication templates have the cheapest per-message price but the strictest content rules: no marketing content, no extra body copy beyond the code itself.
### Location templates
Carry a pinpoint location in the header, useful for store visits, delivery confirmations, or event venues. The user can open the location in their map app with one tap.
**Location header as variables**
The LOCATION header carries up to four fields — **latitude**, **longitude**, **name**, and **address** — and Flowella treats all four as normal template variables.
* The values you typed in the editor (under `_flowellaEditor.headerLocationPreview`) become the **default** sent if no override is supplied.
* The **Test Template** and inbox send dialogs expose the four fields as regular variable inputs.
* HubSpot's [Send WhatsApp Template](/hubspot/workflow-actions#send-whatsapp-template) action passes the four values through `headerLocation` so a workflow can personalise the pin per recipient.
If you omit any of the four at send time, Flowella falls back to the editor preview value for that field.
## Submission lifecycle
When you submit a template from Flowella, it moves through these states:
Saved in Flowella but not yet sent to Meta.
Submitted to Meta and under review. Most templates clear Meta's automated review within minutes, but some are routed for human review. Flowella's editor tells you approval **may take up to 12 hours** and **emails you** the moment the status changes — you don't need to keep refreshing.
Live and usable. You can send it from the inbox, the API, and HubSpot workflows.
Meta declined the template. The rejection reason appears on the template page. Edit and resubmit.
Meta has reviewed quality feedback and flagged the template. Usually a precursor to PAUSED.
Meta has temporarily restricted sending the template, usually because of recipient feedback or low quality. Comes back automatically if quality recovers.
Meta has permanently restricted the template. Must be resubmitted as a new template (often re-categorised) if you want to use the content again.
## Quality rating
Once approved, each template builds up its own quality rating — separate from the [phone number quality rating](/meta/quality-score). The template-level rating uses the same Green/Yellow/Red scale and is driven mostly by:
* Block rate among recipients
* Frequency of "Report" actions in WhatsApp
* Sustained low engagement (no replies, no link clicks)
Yellow and Red template ratings can cause Meta to pause the template even if the phone number's own rating is Green. Watch template quality in **Flowella → Templates** alongside the number-level rating.
## Time-to-live (TTL)
Templates can have a **time-to-live** that controls how long Meta will attempt delivery before giving up. Useful for time-sensitive sends like flash sale invitations.
* **Default:** 30 days for most templates.
* **OTP / authentication templates:** much shorter (a few minutes by default), since codes have no value once stale.
* **Custom TTL:** can be set per-send for some template types.
If a template expires before delivery (recipient phone offline, account paused, etc.), it counts as a send for billing but never reaches the customer.
## Common rejection reasons
* **Promotional content submitted as Utility.** Re-submit as Marketing.
* **Variable samples that don't match the body** — for example, samples that contain links the body doesn't justify.
* **Body or header text that looks like spam** — excessive capitalisation, "Click here", "Free!!!", multiple exclamation marks.
* **Broken or unreachable media header URLs.**
* **Footer text that contradicts the body.**
* **Generic templates** that could be sent by anyone — `Hi {{1}}, special offer for you` without specifics is too generic for marketing approval.
* **Variables in the wrong context** — using a variable in a place Meta doesn't allow it (e.g. some button types).
* **Display name doesn't match the brand** of the template content. If the WABA's display name is "Acme" and the template promotes "Beta Co", it'll be rejected.
Edit a copy of an APPROVED template rather than the original, so you keep a working version while Meta reviews changes. Flowella's **Templates → Duplicate** does this for you, and copies the header media (IMAGE, VIDEO, or DOCUMENT) and the **Document filename** across to the new draft so you don't have to re-upload before publishing. If Flowella can't copy the media (for example when the original sample URL is unreachable), the editor shows a warning and blocks publishing until you re-upload the file.
## Related guides
* [Templates](/app/templates) — the step-by-step of building a template
* [Media headers](/app/media-in-template-headers) — media format reference
* [Template rejected](/troubleshooting/template-rejected) — diagnosing rejections
* [Quality score](/meta/quality-score) — how phone-number quality interacts with template quality
* [Messaging limits](/meta/messaging-limits) — the tier system that constrains how many templates you can send
# Template variables and dynamic content
Source: https://knowledge.flowella.io/app/template-variables
Use variables in WhatsApp template headers, body, buttons, and URLs — syntax rules, sample values, HubSpot personalisation tokens, and rejection traps.
Variables let a single approved template send personalised messages to thousands of contacts without resubmitting to Meta. This page is a deep dive on how variables work in Flowella, where they can appear, and how to wire them up to HubSpot data.
For a high-level overview of template structure, see [Template reference](/app/template-reference). For step-by-step template creation, see [Templates](/app/templates).
## Syntax
WhatsApp templates use **positional variables** with double curly braces and a 1-based index:
```text theme={null}
Hi {{1}}, your booking on {{2}} is confirmed. Reference: {{3}}.
```
Rules:
* Indexes start at `{{1}}` and must be **sequential** — you cannot skip from `{{1}}` to `{{3}}`.
* The same index can be reused inside a single component (body, header, or URL) but Flowella will send the same value to each occurrence.
* Whitespace inside the braces is not allowed: `{{ 1 }}` is invalid.
* Variables are **text only**. Numbers, dates, and currency are sent as strings — format them upstream in HubSpot before sending.
Meta is rolling out **named variables** (`{{first_name}}`) for new templates. Flowella supports both, but positional indexes remain the most reliable format across all template types and Cloud API versions.
## Where variables can appear
| Component | Variables allowed | Notes |
| --------------------------------------------- | ---------------------------- | -------------------------------------------------------- |
| **Header (TEXT)** | 1 | Short values only — no line breaks. |
| **Header (media)** | 1 (the media handle or URL) | Variable is the media itself, not text. |
| **Header (LOCATION)** | 4 (lat, long, name, address) | All four are required when the header is variable. |
| **Body** | Up to \~10 in practice | Each variable counts toward Meta's body character limit. |
| **Footer** | None | Footer is static text only. |
| **URL button** | 1 | Appended to the end of a static base URL. |
| **COPY\_CODE button** | 1 | The full code value. |
| **Quick reply, Phone, Flow, Catalog buttons** | None | Static configuration. |
| **Carousel cards** | Up to 3 per card body | Each card's variables are numbered independently. |
## Sample values
When you submit a template to Meta, every variable needs a **sample value**. Meta uses the samples to:
1. Decide if the template's content matches the chosen category (Marketing, Utility, Authentication).
2. Estimate quality and spam risk.
3. Display a preview to reviewers.
Sample values are not used at send time — they are only for review. But they matter:
* Use **realistic** values. `{{1}} = "John"` is fine; `{{1}} = "xxx"` often triggers rejection.
* Keep samples **short**. Pasting a paragraph into a single variable is a classic rejection signal.
* Make sure the sample is **type-appropriate**. If `{{2}}` is a date, use a date. If it's an order number, use something that looks like an order number.
## Wiring variables to HubSpot data
In a HubSpot workflow that uses Flowella's **Send WhatsApp Template** action:
Flowella shows every approved template for your channel. Variables are auto-detected from the template body, header, and buttons.
For each `{{n}}`, choose a HubSpot contact, company, deal, or ticket property — or type a static value. You can mix personalisation tokens and literal text in the same mapping.
If a contact has no value for the mapped property, the message will fail unless you provide a fallback. Common fallbacks: `"there"` for first name, `"your account"` for account name.
Send the workflow to a single test contact first. Meta rejects sends where any variable is empty, contains only whitespace, or contains a newline.
Empty variables fail at send time, not at template approval. A workflow that runs against thousands of contacts can be silently dropped if a critical property is missing. Always set fallbacks.
## Variable formatting tips
**Names**
```text theme={null}
Hi {{1}},
```
Capitalise the property in HubSpot upstream, or use a HubSpot workflow step to copy `firstname` into a "First name (formatted)" property.
**Dates**
WhatsApp templates do not format dates. If your HubSpot property is `2026-05-24T00:00:00Z`, that's what arrives in the message. Use a HubSpot calculated property or workflow action to format dates as `24 May 2026` before mapping them.
**Currency**
Same as dates — format upstream. Include the currency symbol in the static text (`Total: £{{1}}`) so the variable is just the number.
**URLs in body text**
You can include the full URL inside a body variable, but the link preview will not render and the URL counts against the body character limit. Use a **URL button** with a variable suffix instead:
```text theme={null}
Base URL: https://acme.com/orders/
Variable: {{1}}
At send time: https://acme.com/orders/AB-1234
```
## Common rejection reasons related to variables
* **Skipped indexes** (`{{1}}` then `{{3}}`). Always renumber.
* **Variable at the very start or end** of the body with no surrounding text (`{{1}}` alone). Add a word before or after.
* **Two variables adjacent** (`{{1}}{{2}}`). Separate them with at least a space or punctuation.
* **Sample values that look like placeholders** — `"test"`, `"xxx"`, `"123"` — especially in Marketing templates.
* **Variables in the footer** — not allowed.
* **More than one variable in a URL button** — only one is allowed, and it must be at the **end** of the URL.
## Advanced patterns
### Re-using a value across components
If a customer name appears in both the header and the body, define it once in your workflow and map both `{{1}}` (header) and `{{1}}` (body) to the same HubSpot property. Flowella sends each component its own parameter list, so the indexes are independent — you map the value twice, but you only store it once in HubSpot.
### Conditional content
WhatsApp templates do not support if/else logic inside the template. To send different content to different contact segments, create **separate templates** and branch in your HubSpot workflow — for example, "VIP welcome" and "Standard welcome".
### Multi-language templates
A template's name and structure are shared across languages, but each language is **submitted, approved, and stored separately**. Variables must be in the same positions in every language version. Flowella picks the right language based on the contact's `hs_language` property (or a fallback you configure).
## Troubleshooting
* **Template approved but messages fail with "parameter mismatch"** — Meta and Flowella disagree on how many variables the template has. Re-fetch the template in Flowella (Templates → refresh) so the variable count syncs.
* **Variable shows literal `{{1}}` in the delivered message** — the workflow didn't map a value to that index. Check the workflow action's parameter list.
* **Message rejected at send with "policy violation"** — a variable contains a URL or content that doesn't match the template's category. Marketing-style content cannot be injected into a Utility template via variables.
For the full lifecycle of submitting, editing, and pausing templates, see [Templates](/app/templates) and [Template reference](/app/template-reference). For rejection-specific help, see [Template rejected](/troubleshooting/template-rejected).
# Create, test, and bulk send WhatsApp templates
Source: https://knowledge.flowella.io/app/templates
Build Meta-approved WhatsApp templates with headers, body, and buttons, test on a real device, then bulk send with CSV import, scheduling, and live progress.
![Flowella WhatsApp templates list]()
WhatsApp templates are pre-approved message formats that let you send structured messages to your contacts. They are essential for reaching people outside the 24-hour customer service window — for notifications, updates, reminders, and more. Templates can include rich media such as images and videos, dynamic text variables, and interactive buttons.
## What templates are and why they need Meta approval
Because WhatsApp templates are sent outside the standard conversation window, Meta reviews every template before it can be used. The approval process ensures messages meet WhatsApp's quality standards and business policies. Common rejection reasons include overly promotional language, misleading content, or poor grammar, so it pays to keep your copy clear and focused on genuine value for the recipient.
Once Meta approves a template, you can use it in Flowella workflows, automated flows, campaigns, and manual inbox sends. Any changes to a template's structure require resubmission — but dynamic variables let you personalise each message without additional approvals.
Approval is often near-instant. Meta runs an automated first-stage review that clears most templates within minutes, but anything routed for human review can take **up to 48 hours**. Submit ahead of time so a slower review never blocks a production send.
Looking for a quick reference on categories, header formats, button types, the `{{n}}` variable syntax, or the submission lifecycle? See [Template reference](/app/template-reference).
## Creating a template
### Choose a starting point
Clicking **New Template** (or navigating to `/{org}/templates/new`) opens a chooser with three ways to start:
* **Meta Library** — browse Meta's own catalogue of prebuilt utility templates. These are pre-vetted by Meta and usually approved quickly.
* **Flowella Templates** — a curated catalogue of starter templates that showcase Flowella capabilities (Flow buttons, coupons, re-engagement, and so on).
* **Start from Scratch** — open a blank editor when you already know exactly what you want to build.
You can deep-link straight to a specific tab with the `entry` query parameter — `?entry=meta`, `?entry=flowella`, or `?entry=scratch`. The onboarding setup guide's **Create your first template** step uses `?entry=meta` to land directly on the Meta Library.
Both galleries render **shared WhatsApp preview cards** so what you see while browsing matches the way templates render in the templates catalog — same header, body, and buttons preview.
#### Meta Library gallery
The Meta Library gallery lets you search Meta's utility template catalogue and add templates without rewriting them.
* **Search** — type to filter by name; results are debounced and cached for about an hour per WABA.
* **Language filter** — by default the gallery is filtered to the WhatsApp language derived from your organisation's **content locale** (set under **Settings → Organization**). Toggle **All languages** to browse every Meta locale.
* **Open one as draft** — click **Open as draft** on a card to instantiate that template as a local draft and jump straight into the editor. Nothing is submitted to Meta until you click **Publish**.
* **Multi-select add** — tick the checkbox on multiple cards, then click **Create drafts ()** to instantiate all selected templates at once. On success, Flowella returns you to the templates list.
Library selections always open as **local drafts** in your WABA. You can rename, edit variables, add buttons, or change categories before publishing — the Meta Library entry is just a starting point.
#### Flowella Templates gallery
The Flowella Templates gallery lists curated starters maintained by Flowella (order-status flows, coupon promos, appointment reminders, and so on). Pick a starter to prefill the editor with a ready-to-personalise draft, then publish to Meta when you're happy. Behind the scenes the gallery drops you into the editor via `?starter=`.
### Fill in the editor
Enter a descriptive name that reflects the template's purpose.
Use lowercase letters, numbers, and underscores only — for example, `order_confirmation` or `appointment_reminder`. Spaces and special characters are not allowed by Meta.
Optionally add an image or video as the template header to make your message more engaging.
Header media is optional but recommended. Images must be under 5 MB and videos under 10 MB. Videos should be under 60 seconds and open with an engaging frame.
Enter the main body text for your template. Keep it clear, concise, and relevant to your audience.
Use double curly braces to add dynamic variables — for example, `Hi {{1}}, your order {{2}} is ready for pickup!`. These are replaced with real contact data when Flowella sends the message.
Avoid overly promotional language. Meta's review looks for messages that provide clear value to the recipient.
Click **Add a button to your template** to include an interactive element.
Buttons give contacts a clear next step and increase engagement. You can add up to three buttons per template.
Choose the button type that fits your use case:
* **Call-to-action button** — directs users to a website or phone number.
* **Quick reply button** — lets users respond with predefined text.
* **URL button** — sends users to a specific web page.
You can mix button types on the same template. For example, combine a URL button labelled "View Order" with a quick reply button labelled "Contact Support".
Enter the action or destination for the button — for example, a phone number for a call button or a URL for a link button.
Enter the label that will appear on the button. Make it action-oriented and clear — for example, "Learn More", "Contact Us", or "Get Started".
Button text has a 25-character limit. Use short action verbs and make it obvious what happens when the button is tapped.
Click **Create Template** to save and submit your template.
Submitting the template sends it to Meta for review. This is often near-instant, as most templates clear Meta's automated review within minutes, though some are routed for human review and can take up to 48 hours.
During review, Meta checks for policy compliance. Ensure your template provides clear value to recipients and avoids promotional language that could lead to rejection.
Submitted templates land in the **Pending** state. Most clear Meta's automated review within minutes; some are routed for human review.
Meta tells you approval **may take up to 12 hours** and Flowella will **email you** as soon as the status changes. You don't need to keep refreshing the page.
Once Meta approves the template, you can use it in Flowella workflows, automated flows, the inbox, and bulk sends.
## Delivery-health pills on the templates list
Every row on the templates list can show a **delivery-health pill** in addition to the usual status badge. The pill flags templates that WhatsApp has stopped delivering, so you can spot them without opening each editor.
| Pill | When it appears | What it means |
| ------------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Paused by WhatsApp** | Meta status is `PAUSED`. | WhatsApp paused this template. Journeys, campaigns, and HubSpot workflow actions that use it will not send until Meta restores it. |
| **Disabled by WhatsApp** | Meta status is `DISABLED`. | WhatsApp disabled this template. Update or replace it before sending again. |
| **Quality: Red** | Meta quality score is `RED` and the template isn't already paused or disabled. | WhatsApp rated this template Red. Review recent sends and customer feedback in Meta Business Manager. |
Paused and disabled pills replace the normal status badge; the Quality: Red pill shows alongside it. When Meta lifts the pause, restores the template, or brings quality back to Yellow/Green, the pill clears automatically on the next sync.
Pause, disable, and quality-RED transitions also **fire notifications** (`TEMPLATE_PAUSED`, `TEMPLATE_DISABLED`, `TEMPLATE_QUALITY`) so you find out even if you're not on the templates page. Opt in or out under [Notification preferences](/settings/notification-preferences); the full event list is in [Notification events](/app/notification-events).
## Meta status history
Open any Meta-backed template and switch to the **Statistics** tab. Below the send-log tiles you'll see a **Status history** section that lists every recorded transition Meta has reported for this template — approvals, pauses, disables, quality changes, and category re-classifications — with a timestamp and the source field that changed.
Use this as an audit trail when you're investigating a delivery-health pill or answering "when did this template flip?" in a support conversation.
Status history only appears for Meta-backed templates (not local drafts) and is nested inside the Statistics tab. Earlier versions rendered it below the editor's action bar — it now lives with the rest of your delivery analytics.
## System-managed reopen templates
Flowella's `flowella_reopen_*` templates (Service, Update, Offer) power the Inbox [Reply tab](/app/inbox#reply-tab-smart-reply) and the one-tap [Re-engage CTA](/app/inbox#one-tap-re-engage-on-a-closed-window). In the Templates catalogue these system-managed reopen templates now carry a **System** badge on both the card and list views so you can spot them at a glance.
You can still edit the framing text under [Settings → Reply templates](/settings/reply-templates), but system reopen templates **cannot be deleted** — the delete action is removed from the catalogue row and the delete button inside the template editor is disabled with a tooltip explaining why. To stop using a kind, toggle it off in Reply templates instead.
## Editor behaviour
The template editor is designed to never lose work.
* **Auto-save** — every change to the name, language, category, channel, or components saves after a \~1-second pause. A sticky footer action bar shows the current save state (**Saving…**, **Saved**, or **Unsaved changes**).
* **Publish is gated by save** — the **Publish** button stays disabled until the latest auto-save completes, so you can never submit a half-saved draft to Meta.
* **Body line breaks and footer spaces** are preserved across tab switches and saves — what you type is what Meta receives.
* **Quick Reply buttons start empty** with a placeholder. Saving or publishing a template with an empty Quick Reply text is blocked by inline validation (`BUTTON_TEXT_REQUIRED`).
* **Category dropdown** shows only the selected label when closed; opening it reveals Meta-aligned descriptions, a recategorisation note, and a link to the [Template reference](/app/template-reference).
## Testing a template
To test a template before using it with real contacts, open the template and switch to the **Send** tab.
From **Templates**, click the template you want to test, then select the **Send** tab.
Under **Test Template**, choose the **country code** and enter the WhatsApp number you can receive messages on.
The number must be in international format with the country code — for example, `+44123456789`.
Provide a value for each template variable. For **Coupon code** templates, enter the literal codes you want to send — the template's sample value is **placeholder only** and never used at send time.
Click **Send Test**.
You can send a test even while the template is still pending approval from Meta. Testing lets you see exactly how the message will appear to contacts before using it in production.
Open the message on your device and confirm the header media, body formatting, and buttons render correctly. Check on both iOS and Android if possible.
## Bulk send
The **Send** tab also lets you send an **APPROVED** template to many recipients in one job — useful for marketing announcements, batched reminders, or any structured outbound that doesn't fit in the inbox.
### Building the recipient list
The recipient list editor sits below **Test Template** in the Send tab.
* **Add rows manually** — one row per recipient, with a phone column and one column per template variable.
* **Import from CSV** — click **Import CSV** and pick a file. CSV file import is the only way to import recipients in bulk; pasting rows is not supported.
* **Download the sample CSV** — Flowella generates a starter file with the correct column headers for the selected template (phone + each variable). Use it as the basis for your own list.
* Remove rows with the row-level delete action.
Phone numbers must be in full international format (`+447700900000`). See [Phone number format](/hubspot/phone-number-format).
### Schedule and throttle
* **Schedule** — send immediately, or pick a future date and time.
* **Throttle** — choose how many messages per second Flowella dispatches to Meta. Throttle below your phone number's **messaging limit tier** to avoid spikes that hurt quality score. See [Messaging limits](/meta/messaging-limits).
### Watching the job run
Once you click **Start send**, the **Statistics** tab on the same template shows a live **progress banner** and **job summary tiles**: total queued, sent, delivered, read, failed, and **suppressed**.
While a job is running, the banner and send log refresh automatically every few seconds. You don't need to switch tabs or refocus the window to see new progress. If you open the Statistics tab partway through a job, the banner reappears with the current progress.
The **Suppressed** state is used when Flowella drops a row because the same `(template, phone)` pair was already sent inside the **dedupe window**. This prevents accidental duplicates if you re-import a CSV or re-run a schedule.
You can leave the page — the job continues to run server-side and a notification fires when it completes.
### Failed sends and Resend unsent
If a job finishes without reaching every recipient, Flowella marks it **Failed** instead of reporting an inflated completed count. The progress banner stays visible with the message **Bulk send finished with unsent recipients** and a **Resend unsent** button.
Click **Resend unsent** to requeue only the recipients who never received the message. Recipients that were already sent are not messaged again, so there's no risk of duplicates.
### Per-send Details column
Every row in the **Statistics → Send log** has a **Details** column that explains the outcome in plain English instead of a Meta error code. The Details copy resolves the failure reason from `meta_webhook_logs` and the persisted delivery payload, so post-send Meta failures (for example, payment method **131042**) are surfaced just like pre-send job failures.
| Detail | What it means |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Delivered** | Meta confirmed delivery. |
| **Invalid phone** | The recipient phone number isn't a valid WhatsApp number. |
| **Opted out** | The contact is on the opt-out list. |
| **Contact missing** | The phone wasn't resolvable to a Flowella contact at send time. |
| **Header media URL invalid** | The template has a media header whose sample URL can't be used for sends. Re-upload the media in the editor. |
| **Payment method (131042)** | Meta rejected the send because your WABA's payment method is invalid or has insufficient funds. |
| **Other Meta API error** | A non-deterministic Meta failure — re-send if the issue is transient. |
| **Unknown delivery failure** | Meta accepted the send but later reported it could not deliver. |
Status badges are localized to your account's UI language.
## Related
Categories, headers, buttons, variables, and the submission lifecycle.
Syntax, sample values, HubSpot mapping, and rejection traps.
What media formats and sizes WhatsApp accepts in template headers.
Common Meta rejection reasons and how to fix them.
How template category drives Meta's per-conversation pricing.
Send your approved templates from a HubSpot workflow.
# WhatsApp Web and Desktop: how Flows render outside mobile
Source: https://knowledge.flowella.io/app/whatsapp-web-desktop
How WhatsApp Flows render on WhatsApp Web and the Desktop app, what is supported, and the design choices that matter when customers complete forms on a laptop.
Most WhatsApp conversations still happen on phones, but a significant share of customers — especially B2B and customer-service-led use cases — reply to your messages from **WhatsApp Web** or the **WhatsApp Desktop app**. Up until late 2025, Flows opened on a phone only: a customer on Desktop would see a placeholder telling them to switch devices. Since the rollout of Flows on WhatsApp Web and Desktop, customers can complete forms in the same window as the conversation, which removes one of the biggest friction points in WhatsApp data collection.
This page covers what to expect on each surface, what's not yet supported, and how to design Flows that work well on a laptop.
## Where Flows render now
| Surface | Flows render natively | Notes |
| ------------------------------------------ | ----------------------- | --------------------------------------------------------- |
| **WhatsApp mobile (iOS, Android)** | Yes | The original surface, full feature support |
| **WhatsApp Web** (web.whatsapp.com) | Yes | Modal opens inline; the conversation stays visible |
| **WhatsApp Desktop app** (Windows, macOS) | Yes | Same as Web; modal inside the desktop window |
| **WhatsApp for Linux** | Partial | Via web.whatsapp.com in a browser |
| **WhatsApp Business app (older versions)** | No on desktop companion | Some companion apps still ask the user to open on a phone |
For the customer, this means a Flow message in the conversation expands into a modal panel when they tap it, where they fill in fields and submit. The submission writes back to WhatsApp the same way it does on mobile, and Flowella records the response identically.
The Web/Desktop rollout has been gradual. Some users on older WhatsApp client versions may still see the legacy "please open on mobile" prompt. The system falls back gracefully — they can complete the Flow on their phone when ready — but if you're seeing this in testing, ask the user to update WhatsApp Desktop or refresh WhatsApp Web.
## What changes for your customers
The practical effects of Flows being usable on Web/Desktop:
* **Faster form completion.** Customers don't have to switch devices to fill in their address or pick a date. A typing-heavy form is much faster on a keyboard.
* **Higher completion rates.** Older data showed roughly 30–40% of Flow opens on Web/Desktop being abandoned because of the device-switch friction. That recovers when the form opens in-place.
* **More flexibility around longer forms.** A 6–8 field Flow that would be painful on mobile is fine on a keyboard. You can split fewer forms across multiple screens.
* **Copy/paste works.** A customer pasting a long order number, address, or VAT number into a Flow field can do so naturally.
## What still changes between mobile and Web/Desktop
There are visual and interaction differences you should design around:
The Flow modal on Web/Desktop is a fixed-width panel inside the WhatsApp window. It's narrower than a typical web form and roughly the same width as a mobile screen, so single-column layouts continue to work best. Don't design a Flow that needs side-by-side fields.
Date pickers, dropdowns, and other native form controls use the desktop client's UI on Web/Desktop, which looks different from a phone but behaves the same. Test that any date or time fields render acceptably in both.
Field labels are the thing most likely to differ. Every surface shortens a label that does not fit, and each one has a different amount of room, so a label that reads in full on Web can still be clipped on an iPhone. See [Form design best practices](/app/form-design-best-practices).
Customers on Web/Desktop attach photos or documents from their file system, not from a camera roll. If your Flow asks for "a photo of the damage" expecting an instant camera capture, set expectations in the prompt copy that they may need to take it on their phone first.
Browser geolocation works differently to mobile GPS. If your Flow requests a location, expect lower precision on Web/Desktop and consider an address input as a fallback.
On mobile, WhatsApp can autofill an OTP from a recent SMS. On Web/Desktop, this doesn't happen — the customer types the code manually. Make sure the entry field is clearly labelled as "6-digit code from SMS" or similar.
## Design implications
With Flows running on Web/Desktop, the design decisions worth revisiting:
* **Field count.** You can ask for more fields per screen than was sensible when 30%+ of Web/Desktop users were going to abandon. A 5–7 field screen is reasonable now.
* **Address forms.** Multi-line address forms (street, city, postcode, country) work well on a keyboard. Don't squash these into one line out of habit.
* **Copy-paste fields.** Order numbers, booking references, VAT numbers — fields where the customer is more likely to be on a desktop than a phone — can stay in single inputs rather than being broken up.
* **Confirmation screens.** The end-of-Flow confirmation screen now has more room for a meaningful summary. Use it to confirm the data they entered, not just "thank you".
## How Flowella handles cross-device
From Flowella's perspective, a Flow submission is a Flow submission regardless of which surface the customer used. The webhook payload, the HubSpot form submission event, and the inbox notification are identical.
If you need to know **which surface** the customer used — for analytics or for routing — the response webhook includes a device hint in some message types. Most reporting doesn't need this distinction.
## Testing on Web/Desktop
A quick checklist when building or revising a Flow:
Use Flowella's **Templates → Test Send** or a test contact, with WhatsApp Web open on a second monitor or browser.
Confirm the Flow modal opens inline, not with a "open on mobile" placeholder.
Use Tab between fields, paste long values where realistic, and check that error states (invalid email, missing required field) display readably.
Open the date picker, scroll the dropdowns. Confirm anything that's been tested only on mobile still feels natural with a mouse.
Confirm the response appears in Flowella's Inbox, HubSpot's contact timeline, and your downstream workflow.
## Older clients and fallbacks
If a customer is on an older WhatsApp version that doesn't support Flows on their current surface, WhatsApp typically renders a placeholder asking them to update or open on a phone. The Flow itself is still valid — the customer can complete it later by re-opening the chat on a supported surface.
For business-critical forms, two safeguards:
* **Always include a follow-up message** after a Flow send, asking the customer to confirm they completed it. If they didn't, the auto-reply can prompt them again.
* **Set a reasonable Flow expiry** so the form invitation doesn't sit indefinitely. See [Template reference](/app/template-reference) for the time-to-live options on the underlying template.
## Related guides
* [Forms](/app/forms) — how HubSpot forms become WhatsApp Flows
* [Form design best practices](/app/form-design-best-practices) — label limits, question types, and designing for the narrowest screen
* [Template reference](/app/template-reference) — the template wrapper around a Flow
* [Inbox](/app/inbox) — where Flow submissions land for your team
# Click-to-chat: getting customers into WhatsApp from outside
Source: https://knowledge.flowella.io/campaigns/click-to-chat
Send people into a WhatsApp conversation from your website, emails, social bios, or QR codes using wa.me links — the free counterpart to Click-to-WhatsApp ads.
A **click-to-chat link** opens WhatsApp with a chat to your business number already started. They are free, work without any Meta setup beyond having a registered WhatsApp number, and can be placed anywhere you put a normal link or button — website CTAs, email footers, social media bios, QR codes on packaging, support pages, signature blocks, and so on. This page covers how to build them, where to put them, and how to attribute the conversations they generate.
The easiest way to build a click-to-chat link or QR code in Flowella is to create a **WhatsApp Link** or **QR code** [entry point](/app/entry-points). Flowella gives you a tracked URL you can paste anywhere, counts clicks per entry point, and still lets you set a pre-filled first message. The manual `wa.me` format below is useful when you need to hand-build a link outside Flowella.
If you want to drive WhatsApp conversations from **paid** Facebook or Instagram ads, see [CTWA Ads](/campaigns/click-to-whatsapp-ads). Click-to-chat is the unpaid, organic equivalent.
## The wa.me link format
The basic link is:
```text theme={null}
https://wa.me/
```
For a UK number `+44 20 7946 0000`, the link is `https://wa.me/442079460000`. Notes:
* **No `+`, no spaces, no dashes.** Just digits.
* **Always include the country code.** A bare local number does not work.
* **Use the number registered with WhatsApp Business Platform**, not a different customer service line.
Tapping the link on mobile opens WhatsApp directly. On desktop it opens [web.whatsapp.com](https://web.whatsapp.com) for users who are logged in there, or shows a fallback page prompting them to install or scan a QR code.
## Pre-filling the first message
The `text` query parameter pre-fills the message body the customer sees. Used well, this gives you:
* **Lower friction.** The customer doesn't have to think of what to type first.
* **Routing signals.** The pre-filled text can encode which page or campaign sent them, so your team or your workflow knows the context.
* **Reliable attribution.** Flowella can parse the pre-filled message and write the result back to HubSpot. See [UTM tracking](/hubspot/utm-tracking).
The text must be URL-encoded:
```text theme={null}
https://wa.me/442079460000?text=Hi%2C%20I%27d%20like%20to%20know%20more%20about%20%5BSPRING_LAUNCH%5D
```
Which appears in WhatsApp as:
> Hi, I'd like to know more about \[SPRING\_LAUNCH]
Use a **bracketed code** like `[SPRING_LAUNCH]` or `[NEWSLETTER_JUL]` that the user is unlikely to type by accident. This makes parsing reliable even if the user edits the surrounding text. Keep the code short and human-readable so the pre-fill still looks natural.
## Where to use click-to-chat
### Website CTAs
The most common placement: a "Chat on WhatsApp" button somewhere prominent on your site. Patterns that work:
* **Floating action button (FAB)** on every page, bottom-right. Good for support-oriented sites.
* **In-line CTA** on landing pages, alongside or instead of a "Contact us" form. Useful when WhatsApp is your preferred contact method for a specific campaign.
* **Post-purchase confirmation pages**, offering to send shipping updates via WhatsApp.
Give each placement its own pre-filled code so you can report on which surfaces drive the most conversations.
### Email
Add a click-to-chat CTA to:
* **Order or booking confirmations**, with a code like `[ORDER_SUPPORT_{{order_id}}]` so reps see the context immediately.
* **Newsletter footers**, with a generic `[NEWSLETTER]` code.
* **Sales rep signatures**, with the rep's name embedded: `[REP_ADAM]`.
Works just like a normal `mailto:` or `tel:` link — the user's mobile email client will open WhatsApp when they tap.
### Social media bios
Instagram, Facebook, TikTok, LinkedIn, and X all let you put a link in your bio. A `wa.me` link there is a strong organic capture mechanism for businesses with mobile-first audiences.
Consider using a link shortener (bit.ly, Linktree, etc.) so the URL looks tidy and you can track click-through separately from your other social CTAs.
### QR codes
QR codes that resolve to a `wa.me` link are everywhere now: restaurant tables, packaging inserts, point-of-sale displays, posters at events, business cards. The key advantages:
* The user doesn't have to type your phone number.
* They land in WhatsApp with a pre-filled message giving you context.
* The QR can encode an event-specific code (e.g. `[CONFERENCE_DEMO_BOOTH]`).
Generate the QR code from the full `wa.me` URL, not just from a phone number. Most QR generators handle this natively.
### Sales rep workflows
Reps can paste a personalised `wa.me` link into outbound emails or LinkedIn messages, encoding their own name and the prospect's source. The customer experience is one tap to start a WhatsApp conversation; the rep experience is full attribution back in HubSpot.
## Best practices
Tell the customer what they'll get on WhatsApp. "Get a personal demo — chat with us on WhatsApp" is clearer than just "WhatsApp". Customers who know what they're signing up for block less often.
Many users will tap the link on desktop. WhatsApp Web only works for users already logged in there; everyone else lands on Meta's fallback page. If a significant share of your audience is desktop-first, also offer a form or chat widget as a secondary option, not just the wa.me link.
The pre-filled code identifies the **source**, not the user. Don't try to pack a personal identifier into the code — the user can see and edit it, and personalising it adds privacy risk. Use HubSpot's per-contact properties or `ctwa_clid` for personalised attribution.
A customer arriving via `[SPRING_LAUNCH]` expects a different first response than one arriving via `[ORDER_SUPPORT]`. Use Flowella's keyword-triggered workflows or AI agent routing to deliver the right first message based on the parsed code. See [Workflow Actions](/hubspot/workflow-actions).
Once your team has chatted with you, your number is saved as a contact on their phones, which changes how the link behaves. Always test from a fresh phone or a colleague who hasn't interacted with the business before.
## When to use a button instead of a link
For websites, a styled button is usually better than a raw link:
* **Standard CTAs.** Match the look of your other buttons, use your brand colours.
* **WhatsApp green branding.** If you want the iconic green-button look, Meta provides [official assets](https://developers.facebook.com/docs/whatsapp/business-management-api/branding-guidelines/). Stick to their guidelines so you don't get a takedown notice.
* **Floating action buttons.** Many SaaS platforms (Crisp, Tidio, etc.) provide WhatsApp FAB widgets out of the box.
If you build the button yourself, point it at the `wa.me` link with the appropriate `text` pre-fill.
## Click-to-chat vs CTWA ads
These tools solve different problems and complement each other:
| Feature | Click-to-chat (this page) | [CTWA Ads](/campaigns/click-to-whatsapp-ads) |
| ------------ | ------------------------- | -------------------------------------------- |
| Cost | Free | Paid (Facebook/Instagram ad spend) |
| Surfaces | Anywhere you put a link | Facebook and Instagram ad placements |
| Attribution | Pre-filled text code | `ctwa_clid` from Meta |
| Reach | Your existing audience | Targeted ad audiences |
| Setup effort | Minutes | Hours (ad account, creative, targeting) |
Most businesses run both: click-to-chat on owned surfaces, CTWA for paid acquisition.
## Related guides
* [Entry points](/app/entry-points) — create tracked WhatsApp Link and QR code entry points in Flowella
* [CTWA Ads](/campaigns/click-to-whatsapp-ads) — the paid counterpart
* [UTM tracking](/hubspot/utm-tracking) — attributing conversations back to the campaign that started them
* [Campaigns overview](/campaigns/overview) — where click-to-chat sits in your overall outreach
# Run Click-to-WhatsApp Ad Campaigns with Flowella
Source: https://knowledge.flowella.io/campaigns/click-to-whatsapp-ads
Run structured WhatsApp lead funnels from Facebook and Instagram ads by combining CTWA with keyword-triggered Flowella Flow Templates.
Click-to-WhatsApp (CTWA) ads are Facebook or Instagram ads that send people straight from the ad into a WhatsApp chat with your business when they tap the call to action. Instead of landing on a website or form, they land in a conversation. Flowella fits in after the click: it runs a structured WhatsApp journey, captures answers, and syncs those answers into HubSpot — turning your ad's "Send message" button into a proper lead funnel.
Create a **CTWA** [entry point](/app/entry-points) in Flowella for each CTWA ad you run. Flowella records Meta's click ID (`ctwa_clid`) against the resulting conversation so you can attribute it back to the ad in analytics and HubSpot. The ad itself is still built in Meta Ads Manager, as described below.
## The key limitation: ad-attached flows must be static
In Ads Manager you will see two chat experiences: **Start conversations** and **Collect info with a form on WhatsApp** (Meta's simplified WhatsApp Flows experience).
It is possible to link a WhatsApp ad directly to a Flow using the "Collect info with a form on WhatsApp" experience, but Meta requires that ad-attached Flows be **static** — meaning no data exchange with an endpoint. The moment you need an endpoint to fetch, validate, or personalise data, you are in **dynamic** Flow territory, which is not eligible for that ad placement.
Because a CRM integration depends on exchanging data with your backend (creating or updating HubSpot contacts, checking for duplicates, looking up appointment times, routing logic, and so on), an ad-attached Flow cannot behave like a proper dynamic Flowella flow. Treat "Collect info with a form on WhatsApp" as basic, static lead capture only — not a CRM-connected journey.
## Best practice approach: start a conversation, then trigger a Flow Template
The recommended approach is to use the ad to open a WhatsApp conversation and rely on a keyword to trigger the full Flowella experience:
1. Use the **Start conversations** template in Ads Manager so the ad opens WhatsApp.
2. Set a **pre-filled message (keyword)** so the user's first message reliably triggers automation.
3. Flowella detects that keyword and launches the right **Flow Template**.
4. Flowella syncs the captured data into HubSpot.
This keeps the low-friction ad experience (scroll → tap → WhatsApp), unlocks the full Flowella journey, and lets HubSpot sync work exactly as intended.
## Step-by-step setup
Create a Flow Template tailored to the ad's promise — quote, demo, booking, eligibility check, or similar. Keep it short, purposeful, and mobile-friendly.
Recommended fields for HubSpot lead capture:
* Name
* Email
* One or two qualifying questions (budget, timeframe, service type)
A phone field is not required because it is captured automatically from the WhatsApp number.
Pick a unique phrase that you will use only for that ad. Examples:
* "Hello! Can I get more info on Flowella?"
* "Hello, can I book a Flowella Demo?"
Make it easy to understand, unlikely to appear naturally in other conversations, and unique across your flows.
Case, spacing, punctuation, and mobile autocorrect can all break keyword matching. Keep the phrase short and distinctive, and test it on a real device before launch. Avoid generic phrases like "Hi" — Flowella cannot reliably determine which flow to launch when multiple flows share the same trigger.
Map flow answers to HubSpot contact properties so that each submission becomes a real contact record and can trigger HubSpot workflows.
Create a campaign, choose a messaging-compatible objective, select WhatsApp as the destination, and build the ad as normal.
When you reach the **Chat builder** step:
* Select **Start conversations** (not "Collect info with a form on WhatsApp").
* Set the **pre-filled message** to your keyword — for example, "Hello! Can I get more info on Flowella?"
That pre-filled message is the trigger Flowella will listen for.
Run through the full journey before you spend any budget:
1. Tap the ad.
2. Confirm WhatsApp opens.
3. Confirm the pre-filled message appears.
4. Tap send.
5. Confirm Flowella launches the correct Flow Template.
6. Complete the flow.
7. Confirm the HubSpot contact is created or updated with the right properties.
## Tracking and reporting
You will typically measure results in two places:
* **Ads Manager** — conversations started and cost per conversation (front-end performance).
* **Flowella and HubSpot** — flows started vs completed, leads created, and downstream HubSpot metrics such as MQLs, opportunities, and revenue.
## Common pitfalls
* **Wrong chat template selected in Ads Manager** — selecting "Collect info with a form on WhatsApp" opts you into Meta's limited, static flow experience, not a dynamic Flowella journey.
* **Keyword mismatch** — case, spacing, punctuation, or mobile autocorrect can break triggers.
* **Generic keywords** — if your keyword is "Hi", Flowella cannot reliably decide which flow to run.
* **Overlong flows** — if the flow feels like a mortgage application, completion rates will suffer.
* **No end-to-end QA** — always test from ad click to HubSpot record before scaling spend.
* **Empty chat configuration** — forgetting to set the default message leaves users in a blank conversation with nothing to say.
* **Wrong ad objective** — traffic can work, but Engagement with messages typically produces better conversation rates.
* **Ignoring the 24-hour messaging window** — if you promise a follow-up, act while the conversation window is open, or have approved templates ready for later contact.
## Best practices
1. **Make the value crystal clear in the ad.** Explain what the user gets — for example, "Get a quote on WhatsApp in 2 minutes" or "Chat to book your demo."
2. **Mention WhatsApp explicitly.** Use copy like "Message us on WhatsApp" so people know what will open.
3. **Use a strong default message.** Give the user helpful pre-filled text such as "Hi, I want to book a consultation" to improve the conversion rate from clicks to actual chats.
4. **Keep flows short and purposeful.** Ask only what you need to qualify or fulfil the request; use buttons and lists so users tap rather than type.
5. **Match the ad promise to the flow content.** If the ad says "Get a quote", the flow should ask only the questions needed for a quote and confirm what happens next.
6. **Optimise for conversations, not just clicks.** Use a messaging-conversation objective where possible to encourage delivery to users more likely to engage.
7. **Test the entire journey on a phone.** From seeing the ad through tapping it, through the flow, to arriving in HubSpot — fix anything broken before you scale spend.
8. **Have a plan for human follow-up.** For high-value leads, ensure someone reviews completed flows and can reply personally in WhatsApp within a reasonable time.
## Example flow: "Book a demo on WhatsApp"
A simple pattern you might use in Flowella for a CTWA ad:
| Step | Detail |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ad copy** | "Book a 20-minute product demo, all arranged in WhatsApp." CTA: "Send message on WhatsApp." |
| **Default (pre-filled) message** | "Hi, I'd like to book a demo." |
| **Flow steps** | Ask for name → company → email → preferred timeslot from a list → confirm booking and expectations. |
| **HubSpot mapping** | Name, company, and email mapped to contact fields; preferred timeslot mapped to a custom property; optional task or meeting created by a workflow. |
| **Follow-up** | Sales rep receives a task or notification and confirms the slot by email and/or WhatsApp. |
From a user's perspective, they scroll, tap, answer four or five quick questions, and are done. From your side, a structured lead appears in HubSpot ready for follow-up.
## Related
Compare CTWA ads with the HubSpot-workflow path for outbound campaigns.
Free wa.me links — the organic counterpart to paid CTWA.
Create tracked CTWA, WhatsApp Link, and QR entry points in Flowella.
Attribute CTWA conversations to the campaign that started them.
Build the Marketing / Utility templates that follow the ad-triggered conversation.
Sync the HubSpot form that powers the in-conversation Flow.
# Campaigns overview
Source: https://knowledge.flowella.io/campaigns/overview
Send outbound WhatsApp campaigns from Flowella today using templates and HubSpot lists, and what is planned for native broadcasts and audience segmentation.
A "campaign" in WhatsApp terms is any one-to-many outbound send: a promotion, a reminder, a re-engagement message. This page explains the tools you have today in Flowella to run campaigns, and what we are planning next.
## Two paths today
Flowella supports two production-ready campaign patterns. Pick the one that matches where your audience list lives.
**Recommended for most teams.** If your audience already lives in a HubSpot list, use Flowella's **Send WhatsApp template** action inside a workflow.
* Reuse HubSpot segmentation, suppression, and reporting
* Branch by property and pick a different template per branch
* Delivery, read, and reply data sync back to the contact record
**Best for paid acquisition.** Start the conversation from the recipient's side via a CTWA ad.
* Gets you inside the 24-hour window for free-form replies
* Pairs cleanly with a high-converting Flow form
* Tracks attribution back to the ad campaign
For end-to-end HubSpot recipes, see [Workflow guides](/hubspot/workflow-guides).
## Things to get right before any send
Whichever path you pick, work through this checklist first. Skipping any step is the most common cause of low delivery rates and quality-rating drops.
1. **Opt-ins.** Send only to contacts who have explicitly opted in to WhatsApp from your business. See [Opt-outs](/app/opt-outs) for how Flowella tracks consent.
2. **Right category.** Promotional content must be in a **Marketing** template. Order/account messages go in **Utility**. See [Template reference](/app/template-reference).
3. **Volume warm-up.** New phone numbers have a low daily send limit from Meta. Send small first, increase gradually.
4. **Time of day.** Avoid late-night sends — they correlate with high opt-out rates and quality drops.
5. **Reply plan.** Decide who handles replies in the inbox before they start arriving. See [Inbox](/app/inbox).
## Coming soon: native broadcasts
A native **Broadcasts** UI inside Flowella — pick a template, attach a list, schedule the send, and watch delivery in real time — is on our roadmap. Today, the HubSpot workflow path covers most of the same use cases with the added benefit of full CRM segmentation. We will update this page when broadcasts ship.
Watching for the broadcasts release? Subscribe in **Settings → Notifications** to be told as soon as it's available in your org.
# Flowella product changelog
Source: https://knowledge.flowella.io/changelog
What's new in Flowella: release notes grouped by version, covering new features, template and analytics improvements, HubSpot updates, and bug fixes.
Released 9 September 2026.
## Bug fixes
**Connecting WhatsApp no longer stops with an organisation name error.** Clicking **Connect WhatsApp** or **Reconnect WhatsApp** could previously fail with a red `ORGANIZATION_NAME_REQUIRED` error, even when your organisation already had a name, unless the name had been re-saved in your organisation settings. The connection now starts every time. Your organisation name is still used to prefill Meta's Embedded Signup popup, where you can adjust it before finishing. [Learn more](/account/meta-integration)
Released 8 September 2026.
## Bug fixes
**Full view of a Flow response now shows the contact's answers.** When a Flow submits through a Flow endpoint, choosing **View response** and then **Open full view** on the response card in the inbox could previously open an empty view showing only a dash. Full view now shows the questions and answers the contact submitted. If a submission genuinely contains no answers, you see the message **No answers were returned with this submission** instead. This applies to submissions received from this release onwards. Older Flow responses that opened an empty view stay as they are. [Learn more](/app/inbox#conversation-view)
Released 8 September 2026.
## Bug fixes
**Searching the inbox by name now narrows the list correctly.** Typing a contact's name in the inbox search could previously return every conversation instead of only the matches. Searching by name, phone number, or both now shows just the conversations that match. [Learn more](/app/inbox)
**Links to a specific conversation now open the right thread.** A link that points to a conversation, such as one shared by a teammate, now opens that thread whichever tab it sits in, including **Closed** and **Snoozed**. If the conversation does not exist or belongs to a different WhatsApp channel, you stay on the conversation list and see the message **Conversation not found on this WhatsApp channel**. [Learn more](/app/inbox)
Released 7 September 2026.
## Bug fixes
**The marketing cookies banner now shows its proper wording.** On signed-out pages, such as the login screen, the cookie consent banner could show raw placeholder codes instead of readable text. The banner now reads **Marketing cookies** with **Accept** and **Decline** buttons, as intended. Your choice is remembered exactly as before. [Learn more](/account/login)
Released 7 September 2026.
## Bug fixes
**WhatsApp Flow submissions now reliably reach your HubSpot form.** When a contact completed a WhatsApp Flow that submits to a HubSpot form, HubSpot could accept the submission and then silently discard it if the Flowella domain was not connected to the receiving portal. Flowella no longer includes a conversion page link with these submissions, so they arrive on your form whatever domains your portal has connected. The page name attribution is unchanged and still reads **WhatsApp Flow · \{form name}**, so you can see which form produced each submission. The only visible difference in HubSpot is that the submission's conversion page no longer shows a link to the form in Flowella Forms. [Learn more](/app/forms)
Released 4 September 2026.
## Bug fixes
**Workflows enrolled on Text Reply now always see the reply that triggered them.** A workflow enrolled on the Text Reply activity could occasionally run before the contact's **Last WhatsApp reply message** property had updated, so a branch on the latest reply could read an older answer. Flowella now updates and confirms **Last WhatsApp reply message** and **Last WhatsApp reply at** on the contact before the reply appears in the HubSpot inbox or fires the Text Reply activity. If HubSpot is slow to accept the update, Flowella retries it before letting the reply through. [Learn more](/hubspot/contact-activity#using-activities-in-workflows)
Released 3 September 2026.
## Bug fixes
**Failed HubSpot inbox replies now show the WhatsApp reason.** When a reply sent from the HubSpot inbox through the Flowella Channel cannot be delivered on WhatsApp, HubSpot previously marked it as not delivered without saying why. The failed message now carries the reason WhatsApp gave, including the error code, so you can see at a glance whether the number is unreachable, the message was rejected, or something else went wrong. Replies that fail because the contact opted out or the 24-hour window closed keep the same messages as before, and successful replies are unchanged. [Learn more](/hubspot/custom-channel)
Released 3 September 2026.
## New features
**Copy a template's Meta ID from the catalogue or the template page.** The **⋯** actions menu on each template card and list row now includes **Copy template ID**, which puts the ID Meta assigned to the template on your clipboard. The same ID appears in the info card on the template page, next to **Template ID**, with a copy button beside it. A short confirmation, **Template ID copied**, appears after each copy. Drafts that have not yet been submitted to Meta do not have an ID, so the menu item is disabled with a note explaining that the ID becomes available after submission. Every item in the actions menu now also carries an icon, making the menu quicker to scan. [Learn more](/app/templates)
Released 3 September 2026.
## Bug fixes
**Signing in no longer sends existing organisations back through the name step.** If your organisation already has a real name, you now land on your dashboard or the onboarding hub after signing in. Previously, owners and admins of some longer-standing organisations were asked to name the organisation again on every sign-in, even though a name was already set. New signups still on the default **My workspace** name are still asked to choose a name before connecting WhatsApp. [Learn more](/onboarding)
Released 3 September 2026.
## Bug fixes
**The country selector keeps your choice before you type a number.** Changing the country in a phone number field while the number box was still empty, for example choosing Turkey (+90) under **Test Template** on a template's Send tab, previously snapped the selector back to the default country, such as +44. The country button and the dialling prefix now stay on the country you chose, and keep it if you type a number and then clear it. This applies wherever you pick a country for a phone number, including the phone field on the register and profile pages. [Learn more](/app/templates#testing-a-template)
Released 2 September 2026.
## Updates
**A refreshed look across Flowella.** The app now follows Flowella's updated brand. Headings use the new Stacion typeface, and the Dashboard, Templates, Forms, Inbox, and Settings screens move to the new colour palette, with clearer blues and greens. Status badges, empty states, page headers, and charts now share one consistent style, and message previews in the [Inbox](/app/inbox) sit closer to how WhatsApp renders them. Nothing changes in how features work; only the look is new. [Learn more](/app/dashboard)
Released 2 September 2026.
## New features
**Name your organisation before connecting WhatsApp.** New signups are now asked to set an organisation name before starting the WhatsApp connection. The header shows that name as the workspace switcher, so you always know which organisation you are working in. When you connect a WhatsApp Business Account, Meta's signup flow only prefills a name you set yourself. You can rename the organisation at any time under [Settings → Organization](/settings/organization#organization-name). [Learn more](/onboarding)
**Choose your language before you sign in.** The login and register pages now carry a language selector, so you can use Flowella in your preferred language from the first screen. The language you pick when registering carries into your account after signup. You can change it later from your profile. [Learn more](/settings/profile#locale)
## Updates
**Signing in returns you to the organisation you last used.** If you belong to more than one organisation, Flowella now restores your last-active organisation when you sign in. If you have not opened any organisation yet, a choose-organisation page asks you to pick one. Magic link sign-ins land on the dashboard of that organisation. [Learn more](/account/login)
**Requesting a new magic link retires the old one with a clear message.** If you request a second magic link, opening the older one now explains that a newer sign-in link was sent and offers a **Send me a new link** button, instead of showing an invalid link error. [Learn more](/account/login#magic-link)
**Magic link and reset pages look like Flowella and keep the token out of the address bar.** When a sign-in or password reset link cannot be used, you now land on a branded result page that explains what happened and what to do next. The one-time token no longer stays in the URL. [Learn more](/account/login)
**Sign-in emails greet you by name.** Magic link and password reset emails now use the name on your profile rather than the front of your email address, and registration emails open with a neutral greeting. These account emails no longer carry an unsubscribe footer, because they are needed to run your account. [Learn more](/settings/profile)
**Sign-in email limits.** Flowella sends at most 3 magic link or password reset emails to the same address in a 15-minute window. If you hit the limit, wait a few minutes and use the most recent email. [Learn more](/account/login)
**Repeated wrong passwords slow down instead of locking you out.** Entering the wrong password several times now adds a short, growing delay before the next attempt, rather than failing instantly on every try. [Learn more](/account/login#password)
## Bug fixes
**Reopening a magic link while signed in no longer shows an error.** If you are already signed in and open an old magic link from your inbox, you now land in the app instead of a link already used dead end. If you are signed out and the link is used up, the page offers to send you a fresh link. [Learn more](/account/login#magic-link)
**Registering with an email that already has an account now sends a sign-in email.** Previously, registering with an existing address could quietly go nowhere. Flowella now emails that address a magic link to sign in to the existing account, so you are not left waiting for a confirmation that never comes. [Learn more](/account/login)
**Switching organisation refreshes the whole app straight away.** After moving to another organisation with the switcher, the sidebar setup progress, integration chips, and notification counts now update immediately instead of showing the previous organisation's values. [Learn more](/settings/organization)
Released 2 September 2026.
## New features
**HubSpot inbox replies outside the 24-hour window now fail with a clear reason and Re-engage chips.** WhatsApp only allows free-text replies within 24 hours of the contact's last message. Previously, a free-form reply sent from the HubSpot inbox after that window closed could not be delivered, with little to go on. The message is now marked as failed in HubSpot with the reason **WhatsApp 24-hour window closed, a template is required to re-engage**, and Flowella posts a short note in the thread with quick reply chips. **Re-engage** is always offered and sends the Service reopen template. **Send update** and **Send offer** appear when those reopen templates are enabled and approved. Choose a chip to reopen the conversation with the matching template. Manage the templates under [Settings → Reply templates](/settings/reply-templates). [Learn more](/hubspot/custom-channel)
## Bug fixes
**The register page keeps your details when you switch tabs.** Switching between the **Magic link** and **Password** tabs on the register form previously cleared your email and phone number, and could drop the email into the **Full name** field. Both tabs now carry the email and phone number across the switch, and each field keeps its own value. [Learn more](/account/login)
Released 2 September 2026.
## New features
**Manage templates from a three-dot actions menu in the catalogue.** Every template card in the grid view, and every row in the list view, now carries a **⋯** menu with **Edit**, **Send**, **Statistics**, **Clone**, **Submit for approval**, and **Delete**. **Send** is available once Meta has approved the template. **Submit for approval** appears only for draft and rejected templates. **Statistics** unlocks once the template has been sent. Disabled actions show a short note explaining why. System reopen templates still cannot be deleted; turn them off under [Settings → Reply templates](/settings/reply-templates) instead. Opening the menu on a card no longer navigates into the template. [Learn more](/app/templates)
## Updates
**Template tabs open from links.** Choosing **Send** or **Statistics** from the menu opens the template directly on that tab. The template page also keeps the open tab in the address bar, so you can copy the link while on the Send or Statistics tab and a colleague lands on the same tab. [Learn more](/app/templates)
Released 2 September 2026.
## New features
**Bulk send now accepts Excel recipient files.** The recipient list editor's import control is now **Import file** and takes `.xlsx` files as well as `.csv`. Phone, date, and number cells import exactly as they appear in your spreadsheet, so long phone numbers no longer arrive in scientific notation. Files can be up to 10 MB and 50,000 recipients. Legacy `.xls` files are not supported; save as `.xlsx` or `.csv` first. The **Download sample file** menu now offers the starter file in both **Excel (.xlsx)** and **CSV (.csv)** formats, with the correct columns for the selected template. [Learn more](/app/templates#building-the-recipient-list)
## Bug fixes
**CSV imports handle quoted cells correctly.** CSV files exported from Excel often wrap cells containing commas in quotes. The bulk send recipient import previously split those cells at the comma, which shifted the phone column and broke the list. Imports now follow standard CSV quoting rules, including commas and line breaks inside quoted cells, doubled quotes, and the hidden byte-order mark Excel adds to exports. The same fix applies to the opt-out CSV import. [Learn more](/app/opt-outs#import-contacts-from-csv)
Released 2 September 2026.
## Bug fixes
**Translated interface text no longer shows broken placeholder tokens.** When using Flowella in Portuguese (Brazil), some interface strings showed raw tokens such as `__UTI0__` where a name or number should appear, and some counts displayed the wrong plural form. These strings now render proper Portuguese with the correct values, including confirmation dialogs and template status badges. The same repair applies to Spanish, French, Turkish, and Greek. You choose your interface language from your profile. [Learn more](/settings/profile#locale)
Released 2 September 2026.
## Bug fixes
**HubSpot conversion pages for Flow submissions now link to the form in Flowella.** When a contact completes a WhatsApp Flow that submits to HubSpot, the submission's conversion page attribution previously pointed at a dead `https://whatsapp.flow/` address. It now links to the form in Flowella Forms, scoped to the connected WhatsApp channel where possible, and the page name reads **WhatsApp Flow · \{form name}**, so you can see at a glance which form produced the submission. Submissions recorded with the old address are still recognised, so existing reporting is unaffected. [Learn more](/app/forms)
Released 2 September 2026.
## New features
**The inbox shows the HubSpot contact name when there is no WhatsApp profile name.** Conversation rows and the thread header previously fell back to the raw phone number when a contact had not set a WhatsApp profile name. The inbox now shows the contact's first and last name from HubSpot instead, using the name stored when Flowella links the contact to HubSpot. A contact with a WhatsApp profile name still shows that name first. A contact with neither name shows their phone number in a readable international format, for example `+44 7523 200203`, rather than an unformatted string. Search also matches the HubSpot name, so you can find these conversations by typing the name you know from your CRM. [Learn more](/app/inbox#conversation-items)
Released 2 September 2026.
## Bug fixes
**Inbox messages now show the time the contact sent them.** Inbound messages were previously stamped with the time Flowella received them from WhatsApp, so a Flow response that arrived late could appear after the follow-up template it triggered. Messages are now stamped with the time WhatsApp recorded the send, so Flow responses and text replies sit in the correct order in the conversation, with accurate times. Existing conversations are unaffected; the fix applies to new inbound messages. [Learn more](/app/inbox#conversation-view)
Released 2 September 2026.
## Updates
**Flow response cards now show the Flow's button text as their title.** When a contact completes a Flow, the response card in the inbox previously showed a generic title. It now shows the button text from the message that opened the Flow, for example "Pick your priorities", with a **Response sent** line and a **View response** action inside the card, matching how WhatsApp presents Flow responses. Older conversations pick up the new titles when you open them. [Learn more](/app/inbox#conversation-view)
**Template messages show the template name and language.** Outbound template messages in a conversation now carry a caption underneath in the form **template name · language**, so you can see at a glance which template was sent. The separate **Open full view** button is removed from template messages. It remains on Flow response cards. [Learn more](/app/inbox#conversation-view)
## Bug fixes
**Time and delivery ticks now sit inside template and Flow response cards.** The send time and delivery ticks previously sat outside the preview card for template messages and Flow responses. They now appear inside the card, on one line above the buttons, matching WhatsApp. Plain text and media bubbles are unchanged. [Learn more](/app/inbox#conversation-view)
Released 2 September 2026.
## Bug fixes
**Templates with a variable in the text header now send from HubSpot workflows.** The **Send WhatsApp Template** workflow action previously failed with `Template header expects 1 variable(s); received 0` when the template's text header contained a variable, even with the variable mapped. Flowella now fills the header variable first, then the body variables in order. For a template with one header variable, map **Template Variable 1** to the header and the remaining variables to the body placeholders. Templates with body-only variables or media headers behave as before. If the mapped variables do not match the template, the failure message on the contact's enrolment history now tells you whether the header or the body variables are missing. [Learn more](/hubspot/workflow-actions)
Released 1 September 2026.
## New features
**Branch workflows on the latest WhatsApp reply.** Flowella now writes two properties to the HubSpot contact each time they send an inbound WhatsApp text: **Last WhatsApp reply message** and **Last WhatsApp reply at**. HubSpot filters on the Text Reply activity's **Message** field match against every reply the contact has ever sent, so branch on **Last WhatsApp reply message** instead to route on what the contact just said. Flowella updates the properties before the Text Reply activity fires, so a workflow enrolled on Text Reply always sees the newest reply when it branches. The properties are created when you connect or reconnect HubSpot, and appear automatically on the first inbound reply for accounts that are already connected. If you have existing workflows that filter Text Reply on message content, rebuild those branches to use the new contact property. [Learn more](/hubspot/contact-activity#using-activities-in-workflows)
Released 31 August 2026.
## New features
**Flowella tells pacing and quality pauses apart.** When WhatsApp pauses a template, the templates list now shows which kind of pause it is. A pacing pause, applied after early negative feedback on a new template, shows an **Unpause** button so you can restore the template once you have reviewed its content. A quality pause shows as **Quality pause 1/3**, 2/3, or 3/3, with the time WhatsApp will restore the template automatically. Avoid editing or resubmitting a paused template, as this sends it back to review and extends the outage. [Learn more](/app/templates#delivery-health-pills-on-the-templates-list)
**Sends are held, not lost, while a template is paused.** Bulk sends and HubSpot workflow sends that use a paused or disabled template are now held instead of failing, including jobs you start while the template is already paused. Flowella resumes them automatically when WhatsApp restores the template, or when you unpause a pacing pause. The inbox also labels messages WhatsApp is holding for quality assessment, and tells you when a held message was dropped; dropped messages are not charged. [Learn more](/app/templates#bulk-send)
## Updates
**Drag and drop header sample files.** In the template editor, you can now drag an image, video, or PDF straight onto the header upload area instead of browsing for it. Files of the wrong type or over the size limit are rejected with a clear message. Limits are unchanged: PNG or JPG up to 5 MB, MP4 up to 16 MB, PDF up to 100 MB. [Learn more](/app/media-in-template-headers)
## Bug fixes
**Document header filenames survive publishing.** The filename you set for a document header now stays in place after you publish the template. It shows correctly when you reopen the template and on the document bubble recipients see, without re-uploading the file. [Learn more](/app/media-in-template-headers)
Released 31 August 2026.
## Bug fixes
**Sends triggered from HubSpot no longer fail with an internal error.** After the recent phone number format improvements, an error in phone number checking could stop WhatsApp sends triggered from HubSpot workflows from being processed. Flowella now checks phone numbers the same way everywhere, including HubSpot sends, opt-out matching, and phone fields in the app, so these sends go through as expected. [Learn more](/hubspot/workflow-actions)
Released 31 August 2026.
## Updates
**Phone number fields correct the leading zero for you.** When you type a national number that starts with a zero, for example a UK mobile beginning 07 with +44 selected, Flowella removes the zero as you type and saves the number in valid international format, such as `+447700900123`. This applies wherever you enter a phone number, including the inbox **New message** dialog and bulk send recipient lists. [Learn more](/hubspot/phone-number-format)
## Bug fixes
**Sends from HubSpot to numbers stored with a leading zero now deliver.** If a contact's phone number in HubSpot kept the zero after the country code, such as `+4407700900123`, sends from Flowella workflow actions previously failed as undeliverable. Flowella now converts the number to valid E.164 before sending, so these messages deliver. Storing numbers in clean E.164 format is still recommended. [Learn more](/hubspot/phone-number-format)
**Opt-outs are honoured however the number is formatted.** A contact who opted out could previously still receive messages if their number appeared elsewhere with a leading zero or other formatting differences. Flowella now matches opt-outs on the underlying number, so an opted-out contact is excluded from sends whichever way the number was entered. [Learn more](/app/opt-outs)
**Recipient lists count differently formatted duplicates once.** Bulk send lists and imported CSVs now convert every number to the same international format before removing duplicates, so the same number written two ways receives the message once per job. [Learn more](/app/templates#building-the-recipient-list)
Released 28 August 2026.
## Updates
**The Forms list shows your newest forms first.** The list now defaults to sorting by **Added to Flowella**, newest first, so the forms you added most recently sit at the top. The **HubSpot ID** option has been removed from the **Sort by** menu. Saved links that used it now open with the default sort instead. [Learn more](/app/forms#what-the-list-shows)
## Bug fixes
**Date sorts on the Forms list order correctly.** Sorting by **Modified in HubSpot** now uses the time the form was last edited in HubSpot, and **Flow last synced** uses the time the form's WhatsApp Flow last finished syncing on the selected channel. Forms without a date for the chosen sort appear at the end of the list. [Learn more](/app/forms#what-the-list-shows)
Released 28 August 2026.
## New features
**Resend unsent recipients from a failed bulk send.** When a bulk send finishes with unsent recipients, the progress banner on the **Statistics** tab shows **Bulk send finished with unsent recipients** and a **Resend unsent** button. Click it and Flowella requeues only the recipients who have not received the message, so you finish the job without rebuilding your list or messaging anyone twice. [Learn more](/app/templates#watching-the-job-run)
## Updates
**Duplicate numbers in a recipient list are messaged once.** If your list or imported CSV contains the same phone number more than once, Flowella keeps the first row and drops the repeats before the send starts, so each number receives the message once per job. [Learn more](/app/templates#building-the-recipient-list)
**Bulk sends survive interruptions.** Flowella now records every recipient in a bulk send individually, so a send that is interrupted resumes exactly where it stopped and the progress count on the **Statistics** tab reflects the recipients actually processed. [Learn more](/app/templates#watching-the-job-run)
## Bug fixes
**A bulk send that stops short now shows as failed.** A job could previously be marked complete even though some recipients had not been messaged. Flowella now marks the job as failed while any recipients remain unsent, and the banner stays on screen so you can use **Resend unsent** to finish the job. [Learn more](/app/templates#watching-the-job-run)
Released 27 August 2026.
## Updates
**The AI Document Reader now writes every mapped property, blanks included.** The **AI Document Reader** action writes every property in your field map on each run, including properties the document holds no value for. If a field stops appearing on a document, the matching contact property is cleared rather than left holding an old value. The **Clear HubSpot properties when empty** option is no longer needed and has no effect. Existing workflow steps keep working without changes. [Learn more](/hubspot/workflow-actions)
## Bug fixes
**A mistyped property name no longer loses the whole extract.** If your field map pointed at a contact property that did not exist in your HubSpot portal, HubSpot rejected the entire write and the action failed with `HUBSPOT_PATCH_FAILED`, discarding every correctly extracted value. Flowella now checks your portal's contact properties before writing, skips any names it cannot find, and saves the rest. The step completes and the skipped names are reported to Flowella engineering. [Learn more](/hubspot/workflow-actions)
Released 27 August 2026.
## Bug fixes
**HubSpot file preview links now work in the AI Document Reader.** When the document source held a HubSpot file preview link, the address shown when you open a file inside HubSpot, the **AI Document Reader** action failed with `DOCUMENT_UNSUPPORTED_TYPE`. Flowella now resolves the preview link to the underlying file, so pointing the action at a file property that stores a preview link reads the document as expected. [Learn more](/hubspot/workflow-actions)
**Failure messages name the real problem.** If the document source points at something that is not a file, such as a web page, the action now fails with `DOCUMENT_SOURCE_NOT_A_FILE` so you know the workflow step is misconfigured. If the file is a type Flowella cannot read, the failure message now includes the detected file type, for example `DOCUMENT_UNSUPPORTED_TYPE:application/zip`. [Learn more](/hubspot/workflow-actions)
Released 27 August 2026.
## Updates
**AI Document Reader accepts iPhone photos.** The **AI Document Reader** workflow action now reads HEIC and HEIF photos, the format iPhones use by default. Flowella converts the photo to JPEG before extraction, so contacts can upload an ID photo straight from their camera roll without changing any settings. [Learn more](/hubspot/workflow-actions)
## Bug fixes
**Files uploaded through HubSpot forms now open in the AI Document Reader.** Files that a contact uploads through a HubSpot form are stored behind a secure HubSpot link, and the action previously failed on them with `DOCUMENT_DOWNLOAD_FAILED`. Flowella now fetches these files correctly, so pointing the action at a file property filled by a form upload works as expected. [Learn more](/hubspot/workflow-actions)
**Temporary download problems no longer fail the action straight away.** If HubSpot or the file host has a brief outage while Flowella fetches a document, the action now retries up to three times before reporting `DOCUMENT_DOWNLOAD_FAILED`, so short-lived glitches do not block your workflow. [Learn more](/hubspot/workflow-actions)
Released 27 August 2026.
## New features
**AI Document Reader workflow action in HubSpot.** A new **AI Document Reader** action is available in HubSpot workflows. Point it at a PDF or image using a link, a HubSpot file, or a file property on the contact, and Flowella reads the document and writes the extracted values into the HubSpot contact properties you choose. You define which values map to which properties with a simple field map of up to 40 entries, and you can add optional extraction instructions. A **Clear HubSpot properties when empty** option lets you blank a property when the document holds no value for it. The action reports the properties written and the page count on the enrollment history. [Learn more](/hubspot/workflow-actions)
**Generate Document workflow action in HubSpot.** A new **Generate Document** action fills a Flowella PDF template with the enrolled contact's HubSpot properties and saves the finished PDF to your HubSpot files. You can set an output filename and store the file against a HubSpot property of your choice, and later workflow steps can use the file URL and HubSpot file ID the action returns. [Learn more](/hubspot/workflow-actions)
**Document templates in Settings.** The new **Settings → Document templates** screen is where you create and manage the PDF templates that the **Generate Document** action renders. Build a template from headings, paragraphs, tables, and spacers, and insert contact properties with double-brace tokens such as `{{contact.firstname}}`. Copy the template ID from the list and paste it into the workflow action in HubSpot. [Learn more](/settings/document-templates)
Released 26 August 2026.
## Bug fixes
**Large bulk sends no longer finish early.** A bulk send with a long recipient list could be marked completed after only part of the list had been messaged. Flowella now keeps retrying until every recipient is processed, and recipients who already received the message are skipped, so nobody is messaged twice. If an earlier send stopped short, start a new send from your list rather than reopening the old one. [Learn more](/app/templates#watching-the-job-run)
**The progress banner recognises finished sends.** The banner on the **Statistics** tab no longer shows a send as in progress after the job has completed or failed, even when the send log holds fewer entries than the recipient total. You can dismiss the result instead of watching a bar that never fills. [Learn more](/app/templates#watching-the-job-run)
Released 26 August 2026.
## New features
**API template sends are queued and confirmed straight away.** `POST /v1/templates/send` now returns `202` with a job id as soon as Flowella accepts the request, then delivers the messages in the background. Large batches no longer hold the request open while each message goes out, and Flowella retries temporary WhatsApp errors automatically. If your integration checks for a `200` response, update it to expect `202` with `"status": "accepted"`. You can follow delivery on the template's **Statistics** tab. [Learn more](/api-reference/introduction)
**Duplicate protection with an Idempotency-Key.** Send an `Idempotency-Key` header with `POST /v1/templates/send` and Flowella recognises repeats of the same request for seven days, returning the original job id instead of sending the batch again. You can retry a request after a timeout or network error without messaging anyone twice. [Learn more](/api-reference/introduction)
## Updates
**Header media is prepared once per template.** Repeat sends of a template with an image, video, or document header reuse the media Flowella has already prepared, so a second campaign with the same template starts as quickly as the first. [Learn more](/app/media-in-template-headers)
## Bug fixes
**One failed recipient no longer stops the batch.** If a recipient in a bulk send fails, for example because their number is invalid, the remaining recipients still receive the template. Recipients who already received the message are skipped when a send retries, so nobody is messaged twice. [Learn more](/app/templates#watching-the-job-run)
Released 25 August 2026.
## Bug fixes
**Bulk-send progress no longer freezes on the Statistics tab.** The progress banner now updates every few seconds while a bulk send runs and completes when the last recipient is processed, instead of sticking at zero or stalling below the total on smaller sends. If you open the **Statistics** tab while a job is already running, the banner picks up the real progress rather than starting from zero. [Learn more](/app/templates#watching-the-job-run)
**Send log and summary tiles refresh during a send.** While a bulk-send job is active, the send log and the job summary counters on the **Statistics** tab update automatically, so you can watch a send complete without switching tabs or refreshing the page. [Learn more](/app/templates#watching-the-job-run)
Released 25 August 2026.
## Bug fixes
**Dependent form fields now sync into WhatsApp Flows.** Fields that HubSpot shows conditionally, based on an earlier answer, now carry across when you sync a form, including nested dependent fields. Your WhatsApp Flow matches the full form instead of dropping the follow-up questions. Re-sync an affected form to pick up the fix. [Learn more](/app/forms)
**Required fields no longer fail silently on Flow submission.** Flowella checks required fields before sending a submission to HubSpot, and if HubSpot rejects a field the error now appears in the Flow. If a form's required fields are missing from the Flow, Flowella blocks the sync so you cannot publish a Flow that would fail on submit. [Learn more](/app/forms)
**Workflow actions show the real failure reason in HubSpot.** When a **Send WhatsApp Template**, **Send WhatsApp Message**, or **Send WhatsApp Reply** action fails, the contact's enrollment history in HubSpot now shows the actual error text instead of a generic failure. You can see why a send failed without leaving HubSpot. [Learn more](/hubspot/workflow-actions)
Released 18 August 2026.
## Bug fixes
**Document header filenames survive save and reload.** When you upload a PDF or other document to a template header, the filename now appears in the chip, the field, and the preview straight away, and stays put after you save or reopen the draft. You no longer have to re-upload the file to restore its name before publishing. [Learn more](/app/media-in-template-headers)
**Cloned templates keep their header media.** Cloning a template with an image, video, or document header now copies the sample media into the new draft, so the clone is ready to publish without a silent re-upload. If the copy fails, Flowella still creates the draft and blocks Publish until you replace the media, rather than shipping an empty header. [Learn more](/app/templates)
Released 14 August 2026.
## Bug fixes
**Document headers keep their original filename.** Template sends with a document header now use the filename from the editor or template instead of a Meta CDN placeholder, and Flowella reuses a cached WhatsApp media id for the same file, so recipients see a proper filename and repeat sends are faster. [Learn more](/app/media-in-template-headers)
**HubSpot thank-you formatting survives the Flow sync.** Rich text on HubSpot thank-you screens, including bold, lists, headings, and non-breaking spaces, now renders correctly on the matching WhatsApp Flow thank-you screen after a re-sync. [Learn more](/app/forms)
**HubSpot bullet points stay on one line in WhatsApp Flows.** Nested list items in HubSpot forms and thank-you screens no longer break across two lines when they sync into a WhatsApp Flow. Re-sync an affected form to pick up the fix. [Learn more](/app/forms)
**Plan usage now matches your included conversations.** Starter and Pro plans no longer hard-block sends when you pass the legacy 25,000 or 100,000 caps. The Usage, Dashboard, and Analytics screens show your real included allowance and label anything beyond it as overage, so metered billing lines up with what you are charged for. [Learn more](/account/billing)
**Usage counts only billable conversations.** Free service conversations and other non-billable events from Meta pricing no longer inflate the numbers you see on Usage, Dashboard, and Analytics. [Learn more](/account/pricing-and-conversation-categories)
**Admin search finds organisations by any id.** The admin organisations search now matches both public and internal organisation ids, so pasting either format returns the right record.
Released 7 August 2026.
## New features
**HubSpot timeline previews for Flow submissions and templates.** Flowella now renders inline previews for WhatsApp Flow submissions and template sends directly inside HubSpot contact timeline activities, and Inbox activities gain an **Open full view** link into Flowella. You can review a form answer or a delivered template without leaving the contact record. [Learn more](/hubspot/contact-activity)
**Status history moves into the Statistics tab.** Meta pause, quality, and status changes for a template now live alongside delivery analytics inside the **Statistics** tab on the template editor, instead of sitting below the action bar. Your delivery audit trail and your numbers are in one place. [Learn more](/app/templates#meta-status-history)
## Updates
**Closed tab in the Inbox.** The sidebar adds a **Closed** tab so soft-closed conversations stay reachable. You can reopen a resolved thread from the same list, rather than searching for it. [Learn more](/app/inbox)
**Clearer test-send feedback on templates.** After you send a template test, the confirmation copy now mirrors the send status you see on the Statistics tab, so a queued or failed test no longer reads as delivered. [Learn more](/app/templates)
**Template preview wraps long header text.** The WhatsApp preview inside the template editor now wraps unbroken header tokens the same way it wraps body text, so long words and URLs no longer clip out of the preview frame. [Learn more](/app/templates)
**Arabic and other shipped languages get fuller coverage.** Profile settings and remaining UI strings that still fell back to English on Arabic and other shipped locales are now translated. Switching UI language in Account settings gives you a more consistently localised app. [Learn more](/settings/profile)
## Bug fixes
**WhatsApp Flow submissions now attach to the matched CRM contact.** When a Flow does not ask for an email, Flowella now sends the resolved contact's email with the submission so HubSpot associates the answers with that contact instead of leaving an orphan submission on the form. Existing orphaned submissions can be replayed on request. [Learn more](/hubspot/setup)
**HubSpot timeline activities appear again for all portals.** Flowella now only sends the timeline event properties declared on the HubSpot developer app, so HubSpot no longer rejects the whole batch when an undeclared field is present. WhatsApp activities show on contact records as expected. [Learn more](/hubspot/contact-activity)
**HubSpot workflow actions no longer stall on early validation errors.** When a **Send WhatsApp Message** or **Send WhatsApp Reply** action fails validation early, for example because a template body variable is missing, the workflow step now completes with a failure straight away instead of sitting in a waiting state until HubSpot times out. [Learn more](/hubspot/workflow-actions)
**Emoji round-trip through HubSpot form sync.** Emoji in HubSpot dropdown option labels and other rich text now survive the sync into WhatsApp Flows intact, instead of arriving as replacement characters. Re-sync an affected form to pick up the fix. [Learn more](/app/forms)
**Flow submissions keep working after a failed re-sync.** If a re-sync of an already-published HubSpot form fails, the previously published WhatsApp Flow keeps accepting submissions. Earlier, a failed re-sync could take the live Flow offline until the next successful sync. [Learn more](/app/forms)
**Templates catalogue no longer shows another org's data after switching.** After you switch organisation, the templates list waits for the new WhatsApp channels to load before rendering, so you no longer briefly see the previous org's templates. [Learn more](/app/templates)
**Empty new-message drafts no longer clutter the Inbox.** Conversation shells started from **New message** but never actually sent are now hidden from lists and cleaned up after a short grace period. Your Inbox reflects real conversations only. [Learn more](/app/inbox)
Released 2 August 2026.
## New features
**New Template chooser with Meta Library and Flowella starters.** Creating a template now starts with a clear choice: browse Meta’s template library, pick a Flowella starter (text, media, location, URL, quick reply, or Flow), or start from scratch. Meta library picks open as a local draft so you can edit before publishing to WhatsApp. [Learn more](/app/templates)
**Live 24-hour customer-care countdown in Inbox.** The thread header shows how long you have left to reply in free text, with colour states as the window closes, plus a tooltip for the exact end time. When the window expires, the composer switches to re-engagement automatically. [Learn more](/app/inbox)
**Delivery health on templates.** The templates catalogue surfaces Meta paused/disabled status and red quality scores as attention pills, and admins are notified when templates are paused, disabled, or drop to red quality. Failed inbox sends also show clearer Meta delivery reasons, including marketing-limit guidance. [Learn more](/app/templates)
**Arabic UI language with right-to-left layout.** Account → UI language can switch to Arabic. The app follows with a right-to-left layout, Arabic fonts, and mirrored directional icons. Native copy review continues; expect further polish. [Learn more](/settings/profile)
**Public API on the dedicated API host.** REST v1 is documented and served at the canonical API host (`/v1/...`). Calls to the app host’s `/api/v1/...` redirect to that host when an API public base URL is configured. [Learn more](/api-reference/introduction)
**Template performance drill-down in Analytics.** Open a template row for every send log in your date range, with search, status filters, and CSV/PDF export for that template. [Learn more](/app/analytics)
**Inbox Open and Unseen filters.** Sidebar filters simplify to **Open** and **Unseen**, with unread badges driven from the server when anyone on the team opens a thread. [Learn more](/app/inbox)
**Create a template right after your first Flow sync.** After the first successful HubSpot form → WhatsApp Flow sync, Forms offers a one-time prompt to create a matching template, and every synced form keeps a **Create template** action. [Learn more](/app/forms)
**Setup guide points at starter templates.** The onboarding checklist now steers you to add starter templates via the Meta library gallery, including multi-select add. [Learn more](/onboarding)
## Updates
**HubSpot Timeline links open the right Inbox thread.** Contact activity deep-links use channel-scoped Flowella inbox URLs and HubSpot live-messages thread links when available. [Learn more](/hubspot/contact-activity)
**Clearer Meta delivery error messages.** Codes such as per-user marketing limits and marketing opt-outs map to plain-language explanations in the inbox and template statistics. [Learn more](/troubleshooting/messages-not-delivered)
**Outbound WhatsApp replies appear in the HubSpot inbox.** When the custom channel is connected, messages you send from Flowella (text, templates, Smart Reply) and bulk template sends also show as outgoing in HubSpot’s inbox. [Learn more](/hubspot/custom-channel)
**HubSpot Timeline enums for message type and direction.** Messaging app events stamp message type and inbound/outbound direction so HubSpot workflows and lists can filter reliably. [Learn more](/hubspot/contact-activity)
## Bug fixes
**More reliable HubSpot contact matching and activity linking.** Inbound WhatsApp contact sync paces CRM rate limits, repairs stale HubSpot contact links, writes WhatsApp phone to the dedicated HubSpot WhatsApp phone property, and waits for a CRM contact id before publishing Timeline and custom-channel activity. [Learn more](/hubspot/setup)
**Flow form submits keep answer-owned names.** Form field answers own first/last name on HubSpot submit; WhatsApp profile nicknames are no longer injected as CRM names. [Learn more](/app/forms)
**Billing settings stay put when scrolling.** Settings → Billing no longer jumps to the top when your WhatsApp channel session refreshes; plan cards match live Stripe product copy. [Learn more](/account/billing)
**HubSpot rich text question copy syncs into WhatsApp Flows.** When a HubSpot form places the question in a rich text block above a short-labelled input, the copy now appears in the WhatsApp Flow and the Flowella form preview instead of syncing as an unlabelled input. Headings map to Flow headings, other rich text maps to body text with basic formatting. Re-sync existing HubSpot forms to pick up the copy. [Learn more](/app/forms)
**HubSpot workflows no longer stall when a duplicate template is skipped.** If a HubSpot workflow tries to send the same template twice in a row and Flowella suppresses the duplicate, the workflow step now completes straight away instead of blocking the enrolment until HubSpot times out around an hour later. [Learn more](/hubspot/workflow-actions)
Released 14 July 2026.
## Bug fixes
* **WhatsApp Flow submits stay attached to the HubSpot contact that started the journey.** When a HubSpot workflow enrols a contact and sends them a WhatsApp Flow, Flowella now carries the enrolled HubSpot contact id through to the submit and uses it as the `hs_object_id` on the resulting form submission. Answers land on the same contact the workflow is running against, even when the contact record has no phone number or email that matches the WhatsApp profile. [Learn more](/hubspot/workflow-actions)
* **UK mobile numbers match across `07` and `+44` formats.** Contact lookups from WhatsApp Flow submits and inbound messages now also try the paired UK format, so a contact stored in HubSpot as `07700 900123` is still found when WhatsApp reports the number as `+447700900123`, and vice versa. You get fewer duplicate contacts when your CRM and WhatsApp store numbers in different styles. [Learn more](/hubspot/phone-number-format)
Released 9 July 2026.
## Bug fixes
* **Workflow-enrolled contacts stay linked to their WhatsApp Flow submissions.** When a contact is already enrolled in a HubSpot workflow, Flowella now trusts the stored HubSpot contact id on WhatsApp Flow submits and inbound WhatsApp messages instead of overwriting it with a fresh phone or email lookup. Form-completed events now land on the same contact record the workflow is running against, so you stop seeing duplicate contacts or attribution drifting to an older match. [Learn more](/hubspot/setup)
Released 6 July 2026.
## Bug fixes
* **Typing indicator now shows on every reply path.** The typing bubble that customers see just before a reply lands is now sent consistently when you use **Send WhatsApp Message** and **Send WhatsApp Reply** from HubSpot workflows, when HubSpot inbox agents reply inside the 24-hour window, when messages are sent through the public API, and when you use Smart Reply or send an in-session template from the Inbox. Previously the typing signal only fired from a subset of these paths. [Learn more](/app/inbox#live-typing-indicator-composer--customer)
Released 1 July 2026.
## New features
**Dashboard reimagined as a live activity hub.** The home page now leads with the setup tasks you still need to clear, attention signals such as failed sends, awaiting replies, and billing prompts, and a recent activity feed, all themed to match the rest of Flowella. The card layout keeps your billing, WhatsApp 7-day snapshot, channels, HubSpot status, and forms within easy reach. [Learn more](/app/dashboard)
**Integration status bar.** Every app screen now carries a small status bar at the top with **WhatsApp** and **HubSpot** pill chips. Each chip shows the brand icon, an explicit **Connected** or **Not connected** label, and a status dot. Click a chip to jump straight to the matching settings page. Status refreshes about once a minute, so connecting from another tab shows up quickly. [Learn more](/essentials/multi-channel#integration-status-bar)
## Updates
**Honest plan comparison in Settings → Billing.** The Starter, Pro, and Enterprise cards now describe what Flowella actually ships: included conversations, overage pricing, team seats, HubSpot workflow actions, and support tier. Descriptions and feature bullets are pulled from Stripe so plan copy stays in sync with what you are charged for. Cards share equal heights and a consistent badge row so it is easier to compare plans at a glance. [Learn more](/account/billing)
**Enterprise Contact sales opens the right page.** The Enterprise plan call to action now takes you to [flowella.io/contact](https://flowella.io/contact) so you can reach the sales team directly, instead of landing back inside the app. [Learn more](/account/billing)
**HubSpot dates render in a readable format.** Appointment and date variables coming from HubSpot, including bare epoch values on legacy workflow fields, now display as `dd.MM.yyyy HH:mm` across template sends and custom channel sends, so recipients see real dates instead of long numbers. [Learn more](/hubspot/workflow-actions#date-and-time-variables)
**Clearer Forms sync actions.** Each sync run row now shows a single outline action button that matches the run state: **Try again** for failed runs, **Cancel** for queued or running syncs, and **Create** for forms that have never synced. Run history is preserved across retries. [Learn more](/app/forms#sync-error-ux)
**User-safe Forms sync errors.** Failed syncs surface a readable badge instead of a raw Meta error. `FLOW_SYNC_PREFLIGHT` with Meta `#133010` now points you at finishing phone registration, `QUEUE_FAILED` flags transient queue issues to retry, and Meta `validation_errors` summarise which fields were rejected so you can fix the HubSpot form without leaving the row. [Learn more](/app/forms#sync-error-ux)
**Channel-scoped Forms page.** The Forms list works org-wide, but syncs always target a specific channel. With more than one channel connected, the **Sync** button now stays disabled with a tooltip until you pick a channel, so uploads no longer land on the wrong WhatsApp Business Account. The page also waits for the channel in the URL to resolve before loading, so you do not see a skeleton flash with results from a stale channel. [Learn more](/app/forms#channel-scope-gating)
**Back to setup guide follows you out of onboarding.** When you jump from the **Setup guide** into Forms, HubSpot settings, Templates, the template editor, or the live inbox, a **Back to setup guide** link now appears near the page title, or at the top of the inbox conversation list, so you can return to your checklist in one click. Visit the same pages from the normal sidebar and the link stays hidden. [Learn more](/onboarding)
**More reliable HubSpot workflow callbacks.** When HubSpot rate limits a workflow callback, Flowella now retries the completion so your workflows finish cleanly instead of stalling.
**Smarter contact matching on WhatsApp Flow submits.** Flow form submissions are now resolved by phone number before falling back to email, which avoids attributing a reply to a stale contact when the same email is reused across people.
## Bug fixes
* **Settings → Billing no longer snaps back to the top.** Scrolling to compare plans on the standalone billing page previously jumped you back to the top on route changes. The page now stays where you left it. [Learn more](/account/billing)
* **Correct Starter and Pro upgrade experience.** When upgrading from a Free plan in **Settings → Billing**, you now see in-app **Upgrade to Starter** and **Upgrade to Pro** cards that open Stripe Checkout with the correct base and metered overage line items. [Learn more](/account/billing)
* **Stripe setup intent webhooks acknowledged.** Card updates no longer leave your billing state stuck while Flowella waits for a webhook that was never confirmed.
* **No more duplicate HubSpot contacts from inbound WhatsApp.** When several inbound WhatsApp messages from the same phone number arrived at once, Flowella could create more than one HubSpot contact for the same person. Inbound contact lookups and creates are now serialized per organisation and phone number, so concurrent messages reuse the first HubSpot contact instead of creating duplicates. [Learn more](/hubspot/setup)
* **Empty Quick Reply rows no longer appear in the template live preview**, and inline validation no longer causes layout shift in the editor.
* **WhatsApp template body line breaks are preserved** when switching editor tabs and saving.
* **Unsaved template body and button drafts are kept** when you return to the browser tab.
* **HubSpot settings translations restored** after they were dropped in the dashboard update.
* **HubSpot marketplace connect wizard** now completes reliably end to end when you connect Flowella from the HubSpot marketplace. [Learn more](/hubspot/custom-channel)
Released 19 June 2026.
## Bug fixes
* **Template footer trailing spaces are preserved** when you save the template.
* **Template variable example spacing is preserved** when you save the template.
Released 19 June 2026.
## New features
**Smart Reply in the Inbox.** When the 24-hour customer service window is closed, free text in the new **Reply** tab is automatically wrapped into an approved reopen template (Service, Update, or Offer) so you can keep replying without leaving the conversation. A pricing banner shows the Utility cost up front. [Learn more](/app/inbox#reply-tab-smart-reply)
**Reply templates settings screen.** Edit the framing text around the three reopen templates, track their Draft → Pending → Approved state, and enable or disable each one. Auto-provisioning kicks in when you open the Inbox or Settings, or on an hourly sweep. [Learn more](/settings/reply-templates)
**Send WhatsApp Reply HubSpot action.** A fourth workflow action that picks the right path automatically. It sends as a normal message when the 24-hour window is open, and as a reopen template when it is closed. Branch on `whatsapp_window_open_until` to choose between this and Send WhatsApp Message. [Learn more](/hubspot/workflow-actions#send-whatsapp-reply)
**Open / Unseen and All / Pending tabs.** The conversation list now splits by status (Open / Unseen) and activity (All / Pending), with an org-wide seen watermark so the whole team agrees on what has been read. Recommended workflow: Unseen → Pending. [Learn more](/app/inbox#conversation-list)
**Live typing indicators and read receipts.** The customer sees a typing bubble while an agent is composing, throttled to about once every 20 seconds, and inbound reads now flow back into the conversation view. [Learn more](/app/inbox#typing-indicators-and-read-receipts)
**Per-template send log with drill-down and export.** Open any template from **Analytics** to see every send, filter by status, and export to CSV. [Learn more](/app/analytics)
**HubSpot inbox connect step in onboarding.** A new guided step wires Flowella into the HubSpot inbox during initial setup. [Learn more](/onboarding)
**Redesigned onboarding setup guide.** A 13-step checklist grouped under **Connect**, **Configure**, and **Launch** replaces the old wizard. Progress is auto-detected, you can pause and **Continue later** from the sidebar, and finishing the guide ends in a confetti celebration. New steps cover connecting the HubSpot inbox channel, inviting your team, reviewing reply templates, and sending a test message from Templates → Send. [Learn more](/onboarding)
**Contact activity events toggle.** A new switch in **Settings → HubSpot → Contact activity events** lets you turn off Flowella's timeline events org-wide if you do not want them on the contact record. [Learn more](/hubspot/contact-activity#turn-contact-activity-events-on-or-off)
**Channel-scoped timeline deep links.** Timeline events now link to the right WhatsApp channel inbox automatically, even when your org has multiple numbers, and the HubSpot live messages thread link opens the conversation in the HubSpot inbox. [Learn more](/hubspot/contact-activity#deep-links-from-the-timeline)
## Updates
**Conversation view polish.** Structured template cards and Flow answer rows now render inline so you can see exactly what was sent and what the contact replied.
**Templates statistics tab.** A cleaner layout and new status filters make it easier to spot delivery and read-rate drops. [Learn more](/app/templates)
**HubSpot contact sync reliability.** Inbound activity is now queued behind contact sync, blank first names are backfilled from the WhatsApp display name, and the WhatsApp phone property is written on contact create so timeline links resolve correctly. [Learn more](/hubspot/contact-activity)
**Dedicated WhatsApp phone property in HubSpot.** Contacts created from WhatsApp are now written to **`hs_whatsapp_phone_number`**, with a fallback to the standard `phone` and `mobilephone` properties when matching existing records. [Learn more](/hubspot/phone-number-format)
**Clearer message flow between WhatsApp and the HubSpot inbox.** A new reference table walks through how inbound replies, outbound messages from HubSpot, and templates sent from HubSpot show up on both sides. [Learn more](/hubspot/custom-channel#how-messages-flow-between-whatsapp-and-the-hubspot-inbox)
**Onboarding signals.** Setup guide progress now updates correctly as each step completes. [Learn more](/onboarding)
## Bug fixes
* **Flow contact attribution** on submitted Flows is repaired so the right contact is credited every time.
* **Stale HubSpot contact links** on the inbox no longer stop new activity from being posted.
* **Template status webhooks** are now fanned out to every organisation sharing a WhatsApp Business Account, so approval and rejection updates land wherever the template is used.
Released 9 June 2026.
## New features
**Bulk send for templates.** Send an approved template to many contacts in one go from the **Templates → Send** tab. Build the recipient list in the editor or import a CSV, set an optional schedule and per-minute throttle, and watch live progress as the job runs. The job summary tiles break down delivered, failed, and `Suppressed` (deduped) recipients, and the per-send **Details** column shows a human-readable reason for each failure, for example *Invalid phone*, *Opted out*, or *Payment method required*. [Learn more](/app/templates#bulk-send)
**Per-template analytics drill-down.** Click any template in **Analytics** to open a side sheet with 100% of its send logs. Search by recipient, sort by date, filter with status chips, and export the filtered view as CSV or PDF for finance, ops, or compliance reporting. [Learn more](/app/analytics)
**Coupon code templates.** Promotional templates can now carry a unique coupon code per send. Set codes at send time from the Send tab or directly from the inbox dialog using the new **Coupon code buttons** input. [Learn more](/app/template-reference#specialised-template-types)
## Updates
**Smarter template editor.** Drafts auto-save about a second after you stop typing, and **Publish** is gated on a successful save so you cannot submit stale content. Quick Reply buttons now surface `BUTTON_TEXT_REQUIRED` inline, the category dropdown clearly shows the selected option, and body line breaks plus footer trailing spaces are preserved exactly as written. [Learn more](/app/templates#editor-behaviour)
**Clearer approval expectations.** The **PENDING** state now tells you that Meta review may take up to 12 hours, and you receive an email when the status changes, so you do not need to refresh the templates list. [Learn more](/app/template-reference#submission-lifecycle)
## Bug fixes
* **Template body line breaks** are no longer collapsed on save.
* **Template footer trailing spaces** are preserved.
* **Template variable example spacing** is preserved on save.
* **Category dropdown** now renders the selected label correctly.
Released 8 June 2026.
A follow-up patch to the v2.0.0 replatform. No user-facing changes are documented for this release.
Released 8 June 2026.
Flowella v2 is a full replatform of the product. The sections below cover the user-facing changes that shipped with the initial v2 release.
## New features
**Onboarding setup guide.** A new **//onboarding** hub replaces the old wizard with an auto-detected checklist, progress bar, first sign-in redirect, sidebar entry, and a post-Meta HubSpot connect banner. You can **Continue later** and pick up where you left off. Each step includes a help link to the matching Knowledge Base article. [Learn more](/onboarding)
**Preview mock inbox and templates before you connect.** Org routes for **Inbox** and **Templates** no longer redirect you into onboarding when setup is incomplete. Instead you see a preview mock inbox and a sample templates catalogue so you can explore Flowella before wiring up WhatsApp.
## Updates
**Template Statistics with human-readable failure reasons.** The template send log now includes a **Details** column that spells out why a send failed, for example *Invalid phone*, *Opt-out*, *Contact missing*, or a Meta API error, and status badges use localised labels. When Meta later reports a delivery failure after the initial send (for example payment method code **131042**), the Details column reflects that too. [Learn more](/app/templates#send-log-details)
**Template auto-save and sticky action bar.** The template editor now auto-saves drafts after about a second of inactivity and shows a sticky footer with the current save status. **Publish** is blocked until the auto-save completes so you cannot submit stale content.
**HubSpot custom channel connect wizard.** Connecting Flowella from the HubSpot marketplace now completes end to end. The redirect back into HubSpot works reliably and the inbox no longer shows *Not delivered* for outbound messages. Flowella relays outbound messages from the HubSpot inbox to WhatsApp and reports `SENT` or `FAILED` back to HubSpot. [Learn more](/hubspot/custom-channel)
**HubSpot user templates dropdown scales past 100 templates.** The HubSpot workflow **Template name** dropdown now loads the full list of your Meta templates in pages, and pins your saved selection so the workflow validates even when the value sits outside the first page.
**Transactional email refresh.** All transactional emails now use a branded Flowella shell with a consistent header, onboarding steps, and a shared *Need a hand?* footer.
## Bug fixes
* **Flow endpoint submit success screen.** WhatsApp Flow submits now return the correct thank-you screen so Meta no longer shows a generic submit error after a successful HubSpot submit.
* **Forms photo picker sync.** HubSpot forms with photo or file fields now sync to Meta as WhatsApp Flows without failing on the photo picker validation.
* **Repeat Flow submits.** Repeat WhatsApp Flow submits from the same contact are no longer blocked and each submission emits a fresh `flowella-form-completed` event to HubSpot.
* **Contact names on Flow submits.** WhatsApp Flow form field answers now drive the contact name on HubSpot submit, instead of being overwritten by a WhatsApp profile username.
# How Flowella fits together
Source: https://knowledge.flowella.io/essentials/architecture
A high-level view of how data, messages, and webhooks move between HubSpot, Flowella, and Meta's WhatsApp Business Platform across the full integration.
Flowella sits between your CRM and Meta's WhatsApp Business Platform. This page explains, at a high level, where each piece lives and how data moves between them.
## The three systems
Your source of truth for contacts, forms, properties, and workflows.
Bridges HubSpot and WhatsApp. Owns Flows, templates, the inbox, opt-outs, and the API.
Hosts your WABA, phone numbers, templates, and the WhatsApp Business Platform itself.
## Data flow at a glance
A typical end-to-end interaction looks like this:
A HubSpot workflow, a click-to-WhatsApp ad, or a contact messaging your number kicks things off.
Flowella checks opt-in status, selects the right template or Flow, and resolves any variables from HubSpot properties.
Flowella sends the message via Meta's WhatsApp Business Platform. The contact receives it on WhatsApp.
Replies and Flow submissions come back through Meta's webhooks to Flowella.
Form submissions, Flow responses, and conversation activity sync to the corresponding HubSpot contact, triggering any HubSpot workflows you have set up.
## What lives where
| Concern | System |
| ----------------------------------------------------------------- | -------- |
| Contact records, forms, properties, lists, workflows | HubSpot |
| WABA, phone numbers, templates, display name, message delivery | Meta |
| Flow ↔ form mapping, inbox, opt-outs, API keys, webhooks, billing | Flowella |
## Authentication boundaries
* **HubSpot** is connected via OAuth. You authorise Flowella once during onboarding; the connection is stored at the org level.
* **Meta** is connected through Meta's Embedded Signup. Flowella stores the long-lived access tokens needed to operate the WABA.
* **The Flowella API** is authenticated with API keys you create in **Settings → API keys**.
* **Outbound webhooks** from Flowella are signed so you can verify requests came from us. Configure them in **Settings → Webhooks**.
## Multi-channel and multi-WABA
A single Flowella org can host multiple WABAs and multiple phone numbers. Most app pages are scoped to one channel — you will see the URL change to `/{org}/{waba}/{phone}/…` when you pick a channel. See [Multi-channel and multi-WABA](/essentials/multi-channel) for how to switch between them.
If you are evaluating Flowella for a technical buyer, pair this page with [Data security](/security/data-security).
## Related
How channels, WABAs, and phone numbers map onto Flowella URLs.
Definitions for WABA, channel, conversation, template, and more.
Auth, errors, rate limits, and pagination.
Triage when something is wrong on Flowella, Meta, or HubSpot.
# WhatsApp, Meta, and Flowella glossary of terms
Source: https://knowledge.flowella.io/essentials/glossary
Definitions for the WhatsApp Business, Meta, and Flowella terms you will see across the product, this knowledge base, and the Meta Business Suite UI.
This page collects the terms that appear most often across Flowella, the WhatsApp Business Platform, and HubSpot. Use it as a quick reference when something in the product or another doc page is not clear.
## Workspace and access
Your top-level workspace in Flowella. Billing, team members, API keys, and connected channels all live under an org. URLs in the app start with `/{org}/…`.
A specific WhatsApp sender — the combination of a WABA and a phone number — that Flowella sends and receives messages through. An org can have one or many channels.
Determines what a team member can do inside an org. Flowella uses three roles: **Owner**, **Admin**, and **Member**.
## WhatsApp and Meta
The Meta-side account that holds your WhatsApp Business assets — phone numbers, templates, and business profile. One WABA can contain multiple phone numbers. Flowella connects to one or more WABAs through Meta's official API.
The Meta identifier for a single WhatsApp phone number inside a WABA. Flowella uses the phone number ID (not the dialling number) when sending and receiving messages on the API.
The business name shown to recipients in WhatsApp. Set on the WABA in Meta and reviewed by Meta before approval. See [Display name & profile](/meta/profile-setup).
A pre-approved message format used to start a conversation outside the 24-hour window. Templates have a category (Marketing, Utility, Authentication), a language, and optional variables, buttons, and media. See [Templates](/app/templates).
Meta classifies every template as **Marketing**, **Utility**, or **Authentication**. The category affects pricing and what content is allowed.
The 24-hour period after a contact sends you a message during which you can reply with free-form messages. Outside this window you must use an approved template.
**Opt-in** is explicit consent from a contact to receive WhatsApp messages from your business. **Opt-out** is a contact withdrawing that consent. Flowella tracks opt-out status per contact and blocks outbound sends to opted-out numbers. See [Opt-outs](/app/opt-outs).
Meta ads that open a WhatsApp conversation with your business when tapped. See [Click-to-WhatsApp ads](/campaigns/click-to-whatsapp-ads).
A Meta setup that lets you keep using the WhatsApp Business app on a phone number while also using it through the API via Flowella. See [Coexistence](/meta/co-existence).
## Flows and forms
A native, structured form that runs inside the WhatsApp app. Flowella generates Flows from your HubSpot forms.
The Flowella representation of a HubSpot form, mapped to a WhatsApp Flow. Manage these on the **Forms** page in the app.
## API and developer terms
A secret token you generate in **Settings → API keys** to authenticate requests to the Flowella REST API. Treat API keys like passwords.
An HTTP callback Flowella sends to a URL you control whenever a chosen event happens (for example, a new inbound message). Configured in **Settings → Webhooks**.
Spotted a term we should add? Let us know at [support](https://flowella.io/support).
# Multi-channel and multi-WABA
Source: https://knowledge.flowella.io/essentials/multi-channel
Connect multiple WhatsApp Business Accounts and phone numbers to one Flowella org, switch channels in the app, and read the integration status bar.
A Flowella org can host more than one WhatsApp sender. Each sender — the combination of a WhatsApp Business Account (WABA) and a phone number — is called a **channel**. Most app pages are scoped to a single channel, so you will see the URL change as you switch between them.
## When to use multiple channels
A different phone number per country with localised templates and display names.
Each brand keeps its own WABA, display name, and opt-out list.
Separate phone numbers so reporting and templates don't get mixed.
## URL shape
When a page is channel-scoped, the URL follows this pattern:
```text theme={null}
/{org}/{waba}/{phone}/…
```
* `{org}` — your organisation slug.
* `{waba}` — the WhatsApp Business Account ID.
* `{phone}` — the phone number ID for that channel.
Org-wide pages — Dashboard, Notifications, Forms, Settings — use the shorter `/{org}/…` shape.
## Switching channels
1. Open the channel switcher in the top-left of the app.
2. Pick the WABA, then the phone number you want to work with.
3. The page reloads with the same view scoped to the new channel.
Filters such as inbox queues, analytics ranges, and template lists update to match the channel you selected.
## Adding another WABA or phone number
Go to **Settings → Meta** in the Flowella app.
* To add a **new WABA**, click **Connect WhatsApp** and run through Meta's Embedded Signup again.
* To add a **phone number to an existing WABA**, add it in Meta Business Manager first, then refresh the channel list in Flowella.
Each phone number has its own display name, profile picture, and business info. See [Display name & profile](/meta/profile-setup).
Templates are submitted to a specific WABA. If you want the same template across two WABAs, submit it to each.
## What is shared and what is per-channel
| Scope | Shared across the org | Per channel |
| ------------------------ | --------------------- | ----------- |
| Team members and roles | ✅ | |
| Billing and plan | ✅ | |
| API keys | ✅ | |
| Outbound webhooks | ✅ | |
| HubSpot connection | ✅ | |
| Inbox conversations | | ✅ |
| Templates | | ✅ |
| Analytics | | ✅ |
| Opt-outs | | ✅ |
| Display name and profile | | ✅ |
Opt-outs are recorded per channel because consent is given to a specific business sender. If you operate multiple brands under one org, do not assume an opt-out on Brand A also applies to Brand B.
Plan limits apply at the org level. See [Plans and limits](/account/plans-and-limits).
## Integration status bar
The top of every app screen carries a small **integration status bar** with two pill chips — one for **WhatsApp** and one for **HubSpot** — so you can tell at a glance whether each integration is wired up to the org you're currently viewing.
Each chip shows:
* **Brand icon** (WhatsApp green tick, HubSpot orange logo).
* **Label** — "WhatsApp" or "HubSpot".
* **Explicit status** — **Connected** or **Not connected** (not just a coloured dot).
* A small **status dot** on the right that matches the styling — solid green when connected, muted when not.
Hovering the chip shows a tooltip with a short hint, and clicking it takes you straight to the relevant settings page:
| Chip | Connected click target | Not-connected click target |
| -------- | ------------------------------- | ---------------------------------------------------------- |
| WhatsApp | **Settings → Meta integration** | **Settings → Meta integration** (to start Embedded Signup) |
| HubSpot | **Settings → HubSpot setup** | **Settings → HubSpot setup** (to start OAuth) |
The connected style uses a soft green fill with a sharp border; the not-connected style uses a dashed grey outline so it visibly invites action. Status is cached for 60 seconds — actions you take in another tab (for example, connecting HubSpot from the marketplace) show as connected within a minute, or sooner if you refresh.
The status bar is a quick health check, not a deep diagnostic. If a chip says **Connected** but a feature is still failing — for example, templates won't load — open the matching integration page for the full status, error history, and retry/reconnect controls.
## Related
Where channels and WABAs fit in the wider system.
Add, verify, and migrate the numbers behind each channel.
The WABA that contains your numbers, templates, and quality rating.
Opt-outs are per channel — the most common multi-channel pitfall.
# Status and incidents
Source: https://knowledge.flowella.io/essentials/status-and-incidents
Where to check whether a WhatsApp problem is on Flowella's side, on Meta's side, or in your own integration — status pages, dashboards, and known incidents.
When something doesn't look right, the first question is usually: **is this me, Flowella, or Meta?** Use the status pages below to triage.
## Status pages at a glance
Most "messages not sending" or "delays" issues turn out to be Meta-side. Check this first.
Failed workflow actions and disconnected-integration banners usually trace back to here.
Operational-category notifications broadcast incidents and maintenance windows for your org.
Open a ticket if none of the above explains what you're seeing.
## Meta WhatsApp Business Platform
Check [Meta WhatsApp Business API status](https://metastatus.com/whatsapp-business-api) first. If Meta is reporting an active incident, sends will retry once the platform recovers — there is nothing to fix on the Flowella side.
## Flowella
If Meta looks healthy and Flowella itself appears down or sluggish, in-app notifications are our primary signal. Open **Notifications** (or the bell icon) and look for **Operational** category notifications — we use these to broadcast incidents and maintenance windows that affect your org. See [Notifications](/app/notifications).
Subscribe to operational events by email under [Settings → Notification preferences](/settings/notification-preferences) so you hear about incidents without needing the app open.
## HubSpot
A HubSpot incident will surface in Flowella as failed workflow actions or a disconnected integration banner on **Settings → HubSpot**. Check [HubSpot status](https://status.hubspot.com) before raising a ticket with us.
## Your integration
If neither platform is reporting an incident:
* For **API issues**, check the response body — Flowella returns a structured error envelope. See [API introduction](/api-reference/introduction).
* For **outbound webhooks** that aren't firing, check the delivery log under **Settings → Webhooks**. See [Webhooks](/settings/webhooks).
* For **HubSpot workflow** failures, check the workflow's action history in HubSpot. See [HubSpot sync failures](/troubleshooting/hubspot-sync-failures).
## Reporting an incident to Flowella
If you believe Flowella is having an incident that isn't reflected in your notifications, contact [support](https://flowella.io/support) with:
* Your organisation name
* A timestamp range (UTC) when you first noticed the issue
* A description of what's broken (with a screenshot if possible)
We'll respond on the channel you contacted us on and update affected orgs via in-app notifications and email.
# Flowella contact activity in HubSpot
Source: https://knowledge.flowella.io/hubspot/contact-activity
See every Flowella WhatsApp activity logged on the HubSpot contact timeline, the Timeline v4 event names, and how to use them as workflow triggers.
Every WhatsApp interaction Flowella handles is written back to the HubSpot contact record as a timeline activity, labelled **Flowella: WhatsApp Forms Integration**. This gives your team a full history of WhatsApp engagement next to email, calls, and meetings.
Each activity type is also exposed as a Flowella workflow trigger, and can be used with HubSpot's **Delay until event occurs** action to pause a workflow until the contact does something on WhatsApp.
Contact activity events use HubSpot's **CRM Timeline v4** event API. Behind the scenes the four event types are `flowella-message-sent`, `flowella-message-seen`, `flowella-reply`, and `flowella-form-completed`. You only ever see the friendly labels in the timeline, but the underlying event names matter if you're building custom reports or external integrations on top of HubSpot's API.
## Activities tracked against a contact
| Activity | Recorded when | Workflow trigger | Use with Delay until event | Timeline v4 event |
| -------------- | ------------------------------------------------------- | ---------------- | -------------------------- | ------------------------- |
| Form completed | A contact submits a WhatsApp Flow form sent by Flowella | Form Completed | Yes | `flowella-form-completed` |
| Message sent | Flowella sends an outbound message or template | Message Sent | Yes | `flowella-message-sent` |
| Message read | The contact opens a message Flowella delivered | Message Read | Yes | `flowella-message-seen` |
| Reply received | The contact sends a free text reply | Text Reply | Yes | `flowella-reply` |
## Event properties for filtering
Each Flowella timeline event carries a fixed set of properties defined in the HubSpot developer app. HubSpot rejects the whole batch if Flowella sends any property that isn't declared on the event schema, so the runtime only emits the fields listed below. You can use these properties directly as filter conditions on HubSpot workflow triggers, active lists, and reports for the matching event type.
| Event | Properties |
| -------------- | ----------------------------------------------------------------------------------------- |
| Form Completed | `formName`, `source` |
| Message Sent | `phone`, `deliveryStatus`, `templateName` (set when the message was sent from a template) |
| Message Read | `phone`, `messageType`, `timeToReadSeconds` |
| Reply Received | `phone`, `message`, `responseTimeSeconds` |
`messageType` is an enum on the Message Read event with the values `TEXT`, `IMAGE`, `AUDIO`, `VIDEO`, `DOCUMENT`, `TEMPLATE`, `SYSTEM`, and `OTHER`. It describes the outbound message that was read.
Typical filters:
* **`formName` = `Get Started`** on Form Completed to trigger only on submissions of a specific WhatsApp Flow form.
* **`messageType` = `TEMPLATE`** on Message Read to isolate read receipts of your template sends.
* **`templateName` = `flowella_form_reminder`** on Message Sent to segment contacts sent a specific template.
* **Message contains "cancel"** on Reply Received to build a cancellation intent workflow.
Direction is not currently an event property. Direction is fixed by event type: Message Sent and Message Read are always outbound, and Reply Received is always inbound. Filter on the event itself rather than on a `direction` property.
These properties are set on the timeline event. In workflow triggers they appear as filterable fields under the Flowella event; in HubSpot active lists you can reference them via the timeline event filter for the matching event type.
## What each activity records
### Form completed
Logged when a contact completes a WhatsApp Flow form. The activity records:
* **Form name**: the name of the form completed, for example Get Started
* **Source**: where the submission came from, for example WhatsApp Flow
* **Links**: View submission, View in Flowella
Click **View submission** to open a modal on the contact record that renders the full question-and-answer breakdown of the Flow submission, without leaving HubSpot. The modal is a Flowella-hosted iframe using HubSpot's Timeline v4 iframe support. See [View submission and View template modals](#view-submission-and-view-template-modals) below.
### Message sent
Logged when Flowella sends an outbound message or template to the contact. The activity records:
* **Direction**: `OUTBOUND`
* **Message type**: one of `TEXT`, `IMAGE`, `AUDIO`, `VIDEO`, `DOCUMENT`, `TEMPLATE`, `SYSTEM`, or `OTHER`
* **Status**: Sent
* **Template**: the template name, for example `flowella_form_reminder` (set when the message was sent from a template)
* **Links**: View template, Open in Inbox, View in Flowella
When the outbound message is a template send, the activity card exposes a **View template** link that opens a modal on the contact record showing the rendered template (header, body, footer, buttons, and any variables filled with the values used for this contact). See [View submission and View template modals](#view-submission-and-view-template-modals) below.
### Message read
Logged when the contact opens a message Flowella delivered. The activity records:
* **Phone**: the recipient phone number in E.164 format
* **Message type**: the kind of outbound message that was read — one of `TEXT`, `IMAGE`, `AUDIO`, `VIDEO`, `DOCUMENT`, `TEMPLATE`, `SYSTEM`, or `OTHER`
* **Time to read (seconds)**: how long after delivery the contact opened the message
* **Links**: View message in Flowella
### Reply received
Logged when the contact sends a free text reply. The activity records:
* **Phone**: the contact's phone number in E.164 format
* **Message**: the content of the reply
* **Response time (seconds)**: how quickly the contact replied
* **Links**: Open in Inbox, View in Flowella
## Using activities in workflows
The same four activities power Flowella's HubSpot workflow triggers. You can enrol a contact when an activity occurs, or hold a contact at a **Delay until event occurs** step until it does.
| Activity | Workflow trigger | Typical use |
| -------------- | ---------------- | ----------------------------------------------------- |
| Form completed | Form Completed | Process form answers, then branch on the response |
| Message sent | Message Sent | Log outbound activity or start a follow-up timer |
| Message read | Message Read | Follow up only after the contact has seen the message |
| Reply received | Text Reply | Route the contact based on what they replied |
The strongest pattern is **send then wait**: send a template, add a **Delay until event occurs** step set to a Flowella event such as Form Completed, then branch on whether the event happened in your chosen window. See [Workflow actions](/hubspot/workflow-actions) for the full setup, including how to filter the Text Reply trigger on message content.
## Turn contact activity events on or off
The four events are written by an org-level **capability**. You can switch the whole feature on or off without uninstalling the HubSpot app.
Go to **Settings → HubSpot → Contact activity events** and toggle the switch.
* **On (default)** — Flowella publishes message-sent, message-seen, reply, and form-completed events to every connected contact's timeline.
* **Off** — Flowella stops publishing new events. Existing timeline entries are kept.
Turning the toggle off is useful while you debug a noisy workflow, or if a portal admin wants to keep WhatsApp data out of the CRM timeline temporarily.
## Deep links from the timeline
Each timeline event carries links you can click straight from the activity card:
* **View in Flowella** — uses the **channel-scoped inbox path** (`/{org}/{waba}/{phone}/inbox/...`) so you land on the right channel even if your Flowella account spans multiple WABAs.
* **Open in Inbox** — opens the HubSpot **live-messages** thread for the conversation, so an agent can reply from inside HubSpot.
* **View submission** (Form completed) and **View template** (Message sent, template messages only) — open a Flowella-hosted modal in place on the contact record. See below.
(Behind the scenes, the v4 event payload exposes the first two as `flowellaRecordUrl` and `inboxUrl`. They were previously generic and broke for multi-channel accounts — both URLs are now generated per-channel. The modal links are exposed on the same event as a Timeline v4 `timelineIFrame` field.)
## View submission and View template modals
Form completed and template Message sent activities include an in-place modal that opens on the HubSpot contact record. Clicking the link loads a Flowella-hosted page inside a HubSpot Timeline v4 iframe, so your team can review what was submitted or what a contact actually saw without switching tabs.
| Link | Where it appears | What the modal shows | Modal size |
| ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- |
| **View submission** | Form completed activity card | The submitted Flow's questions and the contact's answers, in order | 720 × 640 |
| **View template** | Message sent activity card, when the send used an approved template | The rendered template (header, body, footer, buttons, and media) with variables filled in with the values used for this send | 420 × 720 |
The modal is powered by a signed, time-limited embed link. Flowella stores a durable snapshot of the submission or rendered template at the moment the activity is written to the timeline, so the modal keeps showing the exact content the contact saw or submitted even if the template is edited or the Flow is updated later.
Links open on the same page as the activity, so hitting **Escape** or clicking outside the modal returns you straight to the contact timeline.
The modal iframe is only allowed on Flowella's `/embed/hubspot/*` paths, and only HubSpot can frame it. The rest of the Flowella app remains same-origin and cannot be embedded elsewhere.
## Finding activities on a contact
Open any contact record and look at the **Activities** timeline. Flowella events show under the **Flowella: WhatsApp Forms Integration** label. To see only WhatsApp activity, filter the timeline by that activity type. These same activities feed the contact and conversation properties used in [Reporting and dashboards](/hubspot/reporting-and-dashboards).
## Related
Set up Flowella triggers and actions in HubSpot workflows.
Report on WhatsApp activity alongside your other channels.
Bring WhatsApp conversations into the HubSpot inbox.
Read and reply to WhatsApp conversations in Flowella.
# Add the Flowella custom channel to HubSpot inbox
Source: https://knowledge.flowella.io/hubspot/custom-channel
Connect Flowella as a HubSpot custom channel so WhatsApp conversations land in the conversations inbox alongside email, chat, and calls for your team.
The Flowella custom channel brings every WhatsApp conversation Flowella manages into the HubSpot [conversations inbox](https://knowledge.hubspot.com/inbox/compose-and-reply-to-emails-in-the-conversations-inbox). Your team reads and replies to WhatsApp threads from the same place they handle email, chat, and calls, and every message is logged on the contact record.
In HubSpot's **Connect a channel** screen, Flowella appears as **Flowella Channel**, next to Team email, Forms, Facebook Messenger, WhatsApp, and Calling.
## What the Flowella channel gives you
* A single inbox for WhatsApp conversations, alongside your other HubSpot channels.
* Automatic routing of new conversations to the right users or teams.
* Replies and templates logged against the contact, visible on the timeline and in reporting.
* The ability to switch between WhatsApp and other channels mid-conversation from the reply editor.
## Requirements
Custom channels are gated by HubSpot, not by Flowella. Your portal needs one of the qualifying subscriptions before the **Flowella Channel** option will appear.
**Available with any of the following HubSpot subscriptions, except where noted:**
* **Sales Hub** Professional or Enterprise
* **Service Hub** Professional or Enterprise
HubSpot Credits may also be required. See HubSpot's guide, [Connect custom channels to the conversations inbox](https://knowledge.hubspot.com/inbox/connect-custom-channels-to-the-conversations-inbox), for the current terms.
Permissions and seats are split across the steps:
| To do this | You need |
| ---------------------------------------------- | --------------------------------- |
| Install the Flowella app in your portal | App Marketplace access permission |
| Connect the channel to the conversations inbox | Super Admin |
| Set routing rules for the channel | A Sales seat or Service seat |
## Before you connect
* Your Flowella account is connected to your HubSpot portal. See [Setup](/hubspot/setup) if you have not done this yet.
* The Flowella app is installed in your HubSpot portal.
* At least one WhatsApp Business Account and phone number are connected in Flowella.
## Connect the Flowella channel
In HubSpot, click the **settings** icon in the top navigation bar. In the left sidebar, go to **Inbox & Help Desk**, then click **Inbox**.
In the top right, click **Connect a channel**, then select **Flowella Channel** from the list of channel types. If it does not appear, confirm the Flowella app is installed and re-authorised against your portal.
Click **Continue with Flowella Channel** and provide the requested credentials in the pop-up window. The fields shown depend on your Flowella channel configuration.
Choose how new WhatsApp conversations are assigned. You can route to specific users and teams, or to the contact owner. Setting routing rules requires a Sales or Service seat.
Click **Next**, then **Done**. The Flowella channel is connected, and incoming WhatsApp conversations now appear in your conversations inbox.
## How messages flow between WhatsApp and the HubSpot inbox
The channel is **bidirectional** — every inbound WhatsApp message is published to HubSpot, and every outbound HubSpot reply is relayed to WhatsApp via Meta with the round-trip status reflected on both sides.
| Direction | What happens |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Inbound (WhatsApp → HubSpot)** | When a contact sends a WhatsApp message, Flowella creates or matches the HubSpot contact and publishes the message to the Flowella channel thread. The same message remains visible in the [Flowella inbox](/app/inbox). |
| **Outbound (HubSpot → WhatsApp)** | When an agent replies from the HubSpot inbox, Flowella forwards the message to Meta and writes the delivery outcome (`SENT` or `FAILED`) back to the HubSpot thread so the agent sees the same status they would in the Flowella inbox. |
| **Templates from HubSpot** | The reply composer lets you send approved templates and Flowella's reopen templates (see [Reply templates](/settings/reply-templates)) when the 24-hour window has closed. |
Connection is handled through Flowella's hosted endpoint at `https://api.flowella.io/api/webhooks/hubspot/channel/connect`. This URL is environment-driven and resolved automatically during the marketplace connect wizard — there's nothing to copy or paste. If you previously saw an **Invalid settings** or 500 error when trying to connect the channel, that issue is now fixed.
## Replying from the inbox
Once connected, WhatsApp conversations behave like any other channel in the inbox. Open the inbox, filter by the Flowella channel if you want to focus on WhatsApp, and reply in real time.
Free text replies are only possible inside WhatsApp's 24-hour customer service window. After 24 hours from the contact's last message, you can only send an approved template. This is a WhatsApp Business Platform rule, not a HubSpot or Flowella limit. See [Using the inbox](/app/inbox) and [Templates](/app/templates).
## Manage or remove the channel
Go to **Settings > Inbox & Help Desk > Inbox**, then hover over the Flowella channel:
* **Edit** to change routing and assignment.
* **Options > Move to help desk** to move the channel and its conversations to help desk.
* **Options > Delete** to remove the channel.
* Toggle the **Status** switch to turn the channel off without deleting it.
## Related
Connect your Flowella account to your HubSpot portal.
Read, reply, and manage WhatsApp conversations in Flowella.
See every WhatsApp activity logged against a contact.
Trigger WhatsApp sends from HubSpot workflows.
# Do WhatsApp contacts need to be HubSpot Marketing Contacts?
Source: https://knowledge.flowella.io/hubspot/marketing-contacts
Flowella does not require HubSpot contacts to be Marketing Contacts to send WhatsApp messages. When you might still want to mark them for your own reporting.
**Short answer: no, Flowella does not require WhatsApp recipients to be HubSpot Marketing Contacts.** WhatsApp messages send to any contact in your HubSpot portal regardless of their Marketing Contact status.
This is one of the more common questions during onboarding, especially from teams who've been on a Marketing Hub Pro/Enterprise plan for a while and are used to the Marketing Contact restriction applying to every outbound channel. The detail matters for two reasons: cost (Marketing Contacts are billed per contact on HubSpot's pricing) and segmentation (lists filtered to Marketing Contacts only would exclude WhatsApp-only audiences otherwise).
## Why the Marketing Contacts restriction doesn't apply
HubSpot's **Marketing Contacts** model gates outbound **Marketing Email** specifically. Contacts set as Non-marketing Contacts cannot receive marketing emails sent from HubSpot.
WhatsApp messages from Flowella are not HubSpot Marketing Emails. They send from Flowella's infrastructure via the WhatsApp Business Platform, using your WhatsApp Business Account and Meta-approved templates. HubSpot's Marketing Contact gate doesn't fire on them, so the messages go out regardless of whether the contact is marked as a Marketing Contact.
This is true for every Flowella send pattern:
* **HubSpot workflow → Send WhatsApp Template** action
* **HubSpot workflow → Send WhatsApp Message** action
* **Flowella Inbox** outbound replies
* **Flowella Campaigns** (manual broadcasts)
* **API-triggered** sends via Flowella's REST API
## What consent you still need
Not being subject to the Marketing Contact gate does **not** mean you can message anyone in your CRM. Two separate consent rules still apply:
WhatsApp's own [Business Messaging Policy](https://business.whatsapp.com/policy) requires that recipients have explicitly opted in to receive WhatsApp messages from your business. "They bought from us once" or "they gave us their number for a phone call" is not opt-in.
The opt-in needs to:
* **Mention WhatsApp explicitly.** A general "keep me informed" checkbox is not enough.
* **Be voluntary.** Pre-ticked boxes don't count.
* **Be auditable.** Keep the timestamp, source, and method of opt-in. Flowella records this on each contact in the **Consent** tab.
See [Managing opt-outs](/app/opt-outs) for how Flowella tracks consent on each channel.
In the UK, EU, and similar regimes, WhatsApp counts as direct marketing the same as email or SMS. The lawful basis you rely on (typically consent, occasionally legitimate interest for transactional messages) still applies.
The Marketing Contact toggle in HubSpot is sometimes used as a CRM-side flag for "we have a marketing consent for this person." If you use it that way, you may want to keep marking opted-in WhatsApp contacts as Marketing Contacts even though Flowella doesn't require it, just to keep your data model consistent.
## Should you mark WhatsApp opt-ins as Marketing Contacts anyway?
Three common positions — Flowella works correctly under any of them.
Keeps your data model consistent: anyone who's consented to marketing of any kind shows as a Marketing Contact in HubSpot. Easier to reason about, and produces accurate counts for HubSpot's contact-tier billing.
Reduces HubSpot Marketing Contact cost. If you have a large list that's opted in to WhatsApp but not email, keeping them as Non-marketing Contacts saves money on HubSpot's billing while still letting Flowella message them.
Leave the Marketing Contact flag for email opt-ins only, and add a custom property like `whatsapp_marketing_consent` (boolean) for WhatsApp opt-ins. Most accurate when you have different consent for different channels.
## How Flowella tracks WhatsApp consent
Independently of the Marketing Contact flag, Flowella records WhatsApp consent on every contact in its own data model:
* **Opt-in source** — form, manual entry, API, or imported
* **Opt-in timestamp** — when the consent was recorded
* **Opt-in method** — e.g. "submitted form `lead-gen-q4` with WhatsApp checkbox ticked"
* **Opt-out events** — if the contact replies STOP, blocks the number, or you record a manual opt-out
This is visible per contact in **Flowella → Contacts → \[contact] → Consent**, and feeds into the audit trail that you'd produce in a GDPR Subject Access Request.
## What if HubSpot's Marketing Email and Flowella WhatsApp run in the same workflow?
A common pattern is a HubSpot workflow that fires both a Marketing Email and a WhatsApp template. In that case:
* The **Marketing Email** step honours the Marketing Contact flag. Non-marketing Contacts get filtered out.
* The **Send WhatsApp Template** step (Flowella) does not. It sends to whichever contacts hit the action, regardless of Marketing Contact status.
If you want the WhatsApp send to also be gated by Marketing Contact status, add a workflow branch filter that checks the Marketing Contact property before the Flowella action.
## Related guides
* [Managing opt-outs](/app/opt-outs) — how Flowella tracks consent and what STOP does
* [Workflow Actions](/hubspot/workflow-actions) — the HubSpot workflow actions Flowella provides
* [Plans and limits](/account/plans-and-limits) — Flowella conversation costs are separate from HubSpot Marketing Contact billing
# WhatsApp Phone Number Formatting for HubSpot and Flowella
Source: https://knowledge.flowella.io/hubspot/phone-number-format
Store WhatsApp numbers in E.164 format in HubSpot, import cleanly from CSV and Excel, and use the formula to convert messy numbers automatically.
If you're using HubSpot to store WhatsApp numbers for Flowella workflows, consistent formatting is essential. Numbers in the wrong format cause failed sends, and the "why is this number missing a digit" mystery is almost always a formatting issue. This page explains the correct format, how to verify it in HubSpot, how to import cleanly, and how to fix a spreadsheet full of messy numbers before import.
## Use E.164 format
Store all WhatsApp phone numbers in **E.164 format**:
* A plus sign `+`
* Country code (no leading zero)
* Full national number (without the leading trunk `0`)
**Examples:**
* UK landline: `+442079460958`
* UK mobile: `+447700900123`
Avoid spaces, brackets, and hyphens. HubSpot displays formatting nicely in the UI, but integrations — including Flowella — work best with plain E.164 values.
## Which HubSpot property holds the WhatsApp number?
Flowella writes WhatsApp-discovered contacts to a dedicated property — **`hs_whatsapp_phone_number`** — rather than the generic `phone` field.
| Scenario | Where Flowella writes / reads |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Inbound message from a contact that doesn't exist in HubSpot yet | A new HubSpot contact is created with the WhatsApp number written to `hs_whatsapp_phone_number`. The generic `phone` property is left empty. |
| Inbound message from a contact that already exists | Flowella searches `hs_whatsapp_phone_number` **first**, then falls back to `phone` / `mobilephone` for legacy contacts. |
| Outbound from a HubSpot workflow | Pick `hs_whatsapp_phone_number` in the **Recipient Phone Number** dropdown of any Flowella workflow action. Falling back to `phone` works but is not recommended for new automations. |
If you have existing contacts whose WhatsApp number sits in `phone` or `mobilephone`, copy it across to `hs_whatsapp_phone_number` with a HubSpot workflow or import. Flowella's search falls back to the legacy fields, but **inbound matching is faster and more reliable when the WhatsApp number is on the dedicated property**.
## Verify a number is valid in HubSpot
When you click into a phone field on a contact record (for example, **Mobile phone number**), HubSpot shows a status under the input. You want it to show **Validated**.
If it does not show Validated:
* Check the number starts with `+` and the correct country code
* Check there is **no leading `0` after the country code** (for example, `+4407…` is wrong — it should be `+447…`)
* Use HubSpot's **Remove number formatting** option if you pasted a messy value, then re-save
A common mistake in Flowella workflows is pointing the action at the **Phone number** property instead of **Mobile phone number**. Double-check which property actually contains the WhatsApp-enabled number.
## CSV and Excel import tips
Excel will "help" by removing the `+` sign or converting long numbers into scientific notation. Prevent this before you import:
* Format the phone column as **Text** (Home → Number format → Text), *then* paste values
* Or prefix values with an apostrophe in Excel: `'+447700900123` — the apostrophe forces text handling and won't appear in the imported data
* In CSV files, wrap values in quotes: `"+447700900123"`
Don't import numbers with spaces or brackets. HubSpot can often normalise formatting, but clean E.164 values give the most consistent results.
## Excel formula: clean phone numbers to E.164
If you have a spreadsheet full of phone numbers in various formats, the formula below will clean them into E.164 format, ready for HubSpot import.
It handles all common input formats, including:
* Local numbers with a leading `0` (e.g. `07700 900123`)
* Numbers with `+` and country code (e.g. `+44 7700 900123`)
* International dialling prefix `00` (e.g. `0044 7700 900123`)
* The `+44(0)7...` format
* Hyphens, dots, brackets, and other punctuation
* Numbers that already have the country code but no `+` (e.g. `447700900123`)
This formula requires **Excel 365 or Google Sheets**. It uses `LET`, `TEXTJOIN`, and `SEQUENCE`, which are not available in older Excel versions.
### How to use the formula
1. Copy the formula below
2. Paste it into any cell in your spreadsheet
3. Change `A2` to point to your first phone number cell
4. Change `"44"` to your country code (see the reference table below)
5. Change `10` to the expected mobile number length for your country
6. Press Enter, then drag down to apply to all rows
### The formula
```excel theme={null}
=LET(
cell, A2,
country_code, "44",
nsn_len, 10,
raw, TRIM(cell&""),
clean, SUBSTITUTE(raw,"(0)",""),
digits, TEXTJOIN("",,IFERROR(MID(clean,SEQUENCE(LEN(clean)),1)*1,"")),
has_plus, ISNUMBER(FIND("+",raw)),
has_00, LEFT(digits,2)="00",
p, LEN(country_code),
starts_cc, AND(LEFT(digits,p)=country_code, LEN(digits)=p+nsn_len),
nsn, IF(has_plus, digits,
IF(has_00, MID(digits,3,999),
IF(starts_cc, MID(digits,p+1,999),
IF(LEFT(digits,1)="0", MID(digits,2,999), digits)))),
intl, IF(has_plus, "+"&digits,
IF(has_00, "+"&MID(digits,3,999),
IF(starts_cc, "+"&digits,
"+"&country_code&nsn))),
is_domestic, AND(NOT(has_plus), NOT(has_00), NOT(starts_cc)),
IF(raw="","",
IF(digits="","REVIEW (not a number): "&raw,
IF(AND(is_domestic, LEN(nsn)nsn_len),"REVIEW (number too long): "&raw,
intl))))
)
```
### What the three config variables mean
| Variable | What to change |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `cell` | The cell containing the raw phone number — change to match your column (e.g. `G2`) |
| `country_code` | The default country code for domestic numbers (e.g. `"44"` for UK, `"1"` for US) |
| `nsn_len` | The expected length of the national subscriber number for mobile numbers in your country (e.g. `10` for UK and US) |
### How the formula works
The formula takes four different paths depending on what it finds in the input:
1. **Has `+` in the original** — already international; strip to digits and prepend `+`
2. **Starts with `00`** — international dialling prefix; strip the `00` and prepend `+`
3. **Starts with the country code AND digit count matches** — bare international (e.g. `447700900123`); prepend `+`
4. **Everything else** — domestic number; strip leading `0` and prepend `+` plus the country code
Before any of this, the formula removes `(0)` from the raw input, so `+44(0)7700 900123` is handled cleanly.
### Invalid number output
Numbers that don't pass validation return a clear message so you can filter and fix them:
| Output | Meaning |
| ---------------------------------------- | ----------------------------------------- |
| `REVIEW (not a number): hello world` | No digits found at all |
| `REVIEW (number too short): 07700` | Not enough digits for a valid number |
| `REVIEW (number too long): 077009001234` | Too many digits, possibly a double prefix |
Length validation only applies to domestic numbers (those without `+` or `00`). Numbers that already have an international prefix are passed through as-is, since the formula cannot know the NSN length for every country.
## Country code reference
| Country | Country Code | NSN Length (mobile) | Notes |
| ---------------------- | ------------ | ------------------- | ----------------------------- |
| United Kingdom | 44 | 10 | |
| United States / Canada | 1 | 10 | All NANP countries share cc=1 |
| France | 33 | 9 | |
| Germany | 49 | 11 | Mobile only; landlines vary |
| Spain | 34 | 9 | |
| Italy | 39 | 10 | Mobiles keep leading 3 |
| Portugal | 351 | 9 | |
| Netherlands | 31 | 9 | |
| Ireland | 353 | 9 | |
| Greece | 30 | 10 | |
| Poland | 48 | 9 | |
| Switzerland | 41 | 9 | |
| Turkey | 90 | 10 | |
| India | 91 | 10 | |
| Australia | 61 | 9 | |
| Japan | 81 | 10 | |
| China | 86 | 11 | |
| UAE | 971 | 9 | |
| Saudi Arabia | 966 | 9 | |
| South Africa | 27 | 9 | |
| Brazil | 55 | 11 | Mobile with 9th digit |
| Singapore | 65 | 8 | |
| Hong Kong | 852 | 8 | |
The NSN length values above are for mobile numbers. For WhatsApp use, mobile-only lengths are correct. If you're processing a mix of mobile and landline numbers, be aware that some countries (especially Germany) have variable-length landlines.
## Quick troubleshooting checklist
If your Flowella workflow actions are failing to deliver messages, work through this checklist:
* Confirm the HubSpot property contains a value in **E.164 format** (starts with `+`)
* Confirm the field shows **Validated** status in HubSpot
* Make sure the number includes the country code and has **no leading `0`** after it
* Ensure your workflow action is pointing at the correct property — the one that actually contains the WhatsApp-enabled number, not a different phone field
## Related
Connect your HubSpot portal and pick which properties Flowella reads.
Pick the right phone property when configuring Send WhatsApp Template.
Phone-format issues are the most common cause of failed sends.
Diagnose individual sends that don't reach the recipient.
# Reporting and dashboards for WhatsApp activity in HubSpot
Source: https://knowledge.flowella.io/hubspot/reporting-and-dashboards
Build HubSpot reports and dashboards that surface Flowella WhatsApp activity alongside email, calls, and meetings using contact and conversation properties.
HubSpot's reporting tools can report on WhatsApp activity natively once Flowella is connected, because Flowella writes structured data back to the HubSpot contact and to a custom **WhatsApp Activity** event timeline. This page covers the reports we recommend setting up first and how to surface them on dashboards.
Flowella also has its own [Analytics](/app/analytics) screen for channel-level WhatsApp metrics. The HubSpot reports here are for cross-channel views where you want WhatsApp alongside email, calls, and meetings on the same dashboard.
## What Flowella writes to HubSpot
For each contact in your portal that Flowella interacts with, the following properties are kept fresh:
| Property | Type | Purpose |
| ----------------------------- | -------- | ---------------------------------------------------- |
| `whatsapp_opted_in` | Boolean | Whether the contact has consented to WhatsApp |
| `whatsapp_first_message_at` | Datetime | First inbound message |
| `whatsapp_last_message_at` | Datetime | Most recent inbound message |
| `whatsapp_entry_source` | String | Campaign or CTWA ad that originated the conversation |
| `whatsapp_campaign_id` | String | Flowella campaign for the most recent conversation |
| `whatsapp_template_last_sent` | String | Most recent template sent to this contact |
| `whatsapp_message_count` | Number | Total messages exchanged with this contact |
| `whatsapp_quality_status` | Enum | Active / opted-out / blocked / undeliverable |
Form submissions made via WhatsApp Flow also create a standard HubSpot **Form Submission** event on the contact, just as if the form had been submitted on your website. This means HubSpot's native attribution, lifecycle stage automation, and lead scoring all work on WhatsApp Flow submissions without any extra plumbing.
## Reports we recommend
### 1. WhatsApp adoption by lifecycle stage
Shows what fraction of each lifecycle stage has opted in to WhatsApp. Useful for spotting which stages have room to push WhatsApp harder.
* **Object:** Contacts
* **Filter:** `whatsapp_opted_in = true`
* **Group by:** `Lifecycle stage`
* **Visualisation:** Stacked column or table
### 2. WhatsApp-influenced deals
Deals where at least one associated contact had WhatsApp activity in the 90 days before close. Sit this next to Email-influenced deals on the dashboard.
* **Object:** Deals (close-date based)
* **Filter:** `Associated contact → whatsapp_last_message_at is in the last 90 days before close date`
* **Group by:** `Deal stage` or `Close month`
* **Visualisation:** Funnel or bar chart
### 3. Source attribution for WhatsApp leads
Shows which campaigns are driving WhatsApp conversations.
* **Object:** Contacts
* **Filter:** `whatsapp_entry_source is known`
* **Group by:** `whatsapp_entry_source`
* **Visualisation:** Bar chart, sorted descending
See [UTM tracking](/hubspot/utm-tracking) for how the entry source is captured.
### 4. Template performance by campaign
Tracks which templates correlate with the highest reply rates. Needs reply data from Flowella.
* **Object:** Contacts
* **Filter:** `whatsapp_template_last_sent is known`
* **Group by:** `whatsapp_template_last_sent`
* **Metric:** Count of contacts where `whatsapp_message_count` is at least 2 (proxy for reply)
### 5. Opt-out and block rate over time
A leading indicator of [quality score](/meta/quality-score) issues.
* **Object:** Contacts
* **Filter:** `whatsapp_quality_status` is `opted-out` or `blocked`, changed in the last 30 days
* **Group by:** Day or week
* **Visualisation:** Line chart
Watch for spikes; they correlate with campaign launches that didn't go well.
## Building a WhatsApp dashboard
We recommend one dashboard per business question rather than one giant "WhatsApp" dashboard. Common splits:
* **Customer Service WhatsApp** — inbox volume, first-response time (from Flowella), opt-outs, quality status
* **Marketing WhatsApp** — template performance, campaign-level attribution, conversion to deal
* **Sales WhatsApp** — SDR pipeline activity, WhatsApp-influenced deals, win rate by entry source
Each uses different cuts of the same underlying data.
## Cross-channel comparisons
The most useful WhatsApp reports often **don't** filter to WhatsApp — they're cross-channel comparisons where WhatsApp is one slice.
Examples:
* **Engagement by channel.** Reply rate, time-to-reply, and resolution time across email, WhatsApp, and live chat. Often surprises people: WhatsApp typically has higher reply rates but shorter sessions than email.
* **Cost per qualified lead by channel.** Combines Flowella's per-conversation cost (from Plans & Limits), HubSpot's email send cost, and your ad spend to give a per-MQL cost by channel.
* **Source → deal velocity.** How long from first WhatsApp touch to closed-won deal vs. first email touch.
These reports need data from outside HubSpot too (cost data in particular), so consider piping them through a BI tool. Flowella's data is queryable via the REST API; see [API reference](/api-reference/introduction) for the endpoints.
## Tips for accurate reporting
HubSpot's native Sequence reporting won't include Flowella's WhatsApp sends. If your reps use both, build a unified "sequence activity" view in Flowella's Analytics rather than relying on HubSpot's sequence-only dashboards.
Flowella records timestamps in UTC. HubSpot reports group by the **portal's** time zone (set in HubSpot Settings). Make sure these match if you're comparing Flowella Analytics to HubSpot reports for the same period — a small UTC vs local-time mismatch can shift a metric by a day.
HubSpot's pre-built single-object reports work for most basic WhatsApp views. For cross-channel and time-to-conversion analysis, use the custom report builder so you can join contacts and deals.
## Related guides
* [Analytics](/app/analytics) — Flowella's native WhatsApp metrics, including the metrics that don't have a HubSpot equivalent
* [UTM tracking](/hubspot/utm-tracking) — setting up the entry-source attribution that drives several of the reports above
* [Workflow Actions](/hubspot/workflow-actions) — the workflow actions that generate the activity these reports surface
# Connect Flowella to HubSpot: Step-by-Step Setup Guide
Source: https://knowledge.flowella.io/hubspot/setup
Create your Flowella account, connect Meta WhatsApp Business, add a payment method, and link your HubSpot portal in one guided walkthrough.
This guide walks through the HubSpot side of Flowella onboarding: creating your Flowella account, completing the Meta connection, linking your HubSpot portal via OAuth, and picking a Quick Start template to get a working configuration in minutes.
If you don't yet have a Meta business portfolio, WhatsApp Business Account, or verified phone number, complete the Meta setup first. See [Setup sequence](/meta/setup-sequence) for the full Meta-side walkthrough — it covers business verification, phone numbers, display name approval, and payment method in order. Come back to this page when your WABA is approved and ready to send.
## Prerequisites
* **HubSpot:** Super Admin role, or permission to install marketplace apps and manage integrations and workflows.
* **Meta / Facebook Business:** Admin access to your Business Manager and a WhatsApp Business Account (WABA) ready to connect. See [Setup sequence](/meta/setup-sequence) if you're starting from scratch.
* **Payment method:** A Visa, Mastercard, or Amex ready to add to your WABA. Meta bills WhatsApp conversation charges directly to this card.
Meta requires a payment method on your WhatsApp Business account before business-initiated messaging is fully enabled. Without one set as **Default** on the WABA, outbound messages will be limited or blocked once you exhaust the free service tier. Flowella does not charge or store this card — it is billed directly by Meta. See [Meta payment method](/meta/payment-method) for the full walk-through.
## Setup walkthrough
Go to [app.flowella.io](https://app.flowella.io/) and click **Create account**. Enter your email address and a secure password, then click **Create account** to continue.
After signing in, you'll land on the **Welcome to Flowella!** screen. Click **Continue Setup** to begin the guided onboarding flow.
On the **Meta Authentication** screen, click **Connect WhatsApp Business**. You'll be redirected to Facebook to grant Flowella access via Meta's Embedded Signup flow, where you'll choose or create your business portfolio, WABA, and phone number, and confirm Flowella's permissions.
If your WhatsApp display name is pending Meta review, you can still proceed with setup. Approval typically happens in the background, and messaging limits expand automatically as your account warms up. See [Display name & profile](/meta/profile-setup).
After Embedded Signup completes, you'll see **"You're now ready to chat with people on WhatsApp"**. Click **Add payment method** to attach a card to your WABA, then click **Finish**.
The card sits at the WABA level on Meta, not in Flowella. After adding it, confirm it shows the **Default** badge on the WABA — if it doesn't, Meta will continue billing whichever card was Default before, and you'll see a "payment method missing" warning despite the new card being attached. See [Meta payment method](/meta/payment-method) for the full walk-through.
You'll now see HubSpot's OAuth flow:
1. Click **Sign in to your HubSpot account** (or create a new account if you don't have one yet).
2. Select the correct HubSpot portal from the account picker and click **Choose Account**.
3. Review the scopes Flowella is requesting and click **Connect app**.
After the redirect, Flowella will show **Connected to HubSpot** along with your Portal ID. Click **Continue**.
On the **Choose Your Setup Approach** screen, you have two options:
**Quick Start Templates** — select a pre-built template to auto-provision a working configuration you can edit immediately. Available templates include:
* **Marketing Outreach** (Popular) — a compliant campaign flow using approved templates
* Identity Verification, Contact Details Refresh, and Event Registration (coming soon)
**Custom Flow** *(coming soon)* — build your own WhatsApp Flow mapped to your HubSpot forms and contact properties.
Choose a Quick Start Template if you want a working example quickly. You can edit the questions, template variables, and property mappings after setup.
Once setup is complete, your Flowella account is connected to both Meta and HubSpot and you're ready to build workflows. See [Workflow Actions](/hubspot/workflow-actions) for a full guide to configuring triggers and actions in HubSpot.
## Troubleshooting
If anything in Meta's setup gets stuck — Start Verification button greyed out, display name rejected, payment method warning that won't clear — see the [Troubleshooting](/troubleshooting/onboarding) page. The most common Meta-side issues and their fixes are covered there with links back to the relevant `/meta/` reference pages.
# UTM tracking from WhatsApp to HubSpot
Source: https://knowledge.flowella.io/hubspot/utm-tracking
Attribute WhatsApp conversations to the campaign that started them using UTM parameters on Click-to-WhatsApp ads, click-to-chat links, and CTWA tracking.
When a customer reaches you via WhatsApp, the most valuable bit of context is **where they came from**: which Click-to-WhatsApp (CTWA) ad they tapped, which website link, which email campaign. Without that attribution, your reporting collapses into "WhatsApp" as a single source. With it, you can compare campaigns, calculate ad ROAS, and feed proper attribution into HubSpot deals.
This page covers the three patterns Flowella supports for moving campaign attribution from WhatsApp into HubSpot.
## Pattern 1: Click-to-WhatsApp ads (`ctwa_clid`)
Facebook and Instagram CTWA ads attach a click ID (`ctwa_clid`) to every conversation they originate. Meta passes this ID into the conversation context when the user taps the ad and starts the chat, and Flowella forwards it to HubSpot on the contact record.
Flow:
1. Customer sees a CTWA ad on Facebook or Instagram.
2. Customer taps the **Send Message** button on the ad. WhatsApp opens with a pre-filled message and Meta records the `ctwa_clid`.
3. Customer sends the message. Flowella receives the inbound message with `ctwa_clid` in the metadata.
4. Flowella creates or updates the HubSpot contact with the `ctwa_clid` value on a dedicated property.
5. Flowella also stores the `ctwa_clid` against the conversation so analytics can join back to the ad spend.
Meta's Conversions API integration to send conversion events back to Facebook Ads Manager uses the same `ctwa_clid`. See [CTWA Ads](/campaigns/click-to-whatsapp-ads) for setting this up so you can optimise ad spend on actual conversions, not just clicks.
## Pattern 2: Click-to-chat links from your own pages
When you put a **Chat on WhatsApp** button on your website or email, you'll use a `wa.me` link. The link supports a `text` parameter that pre-fills the user's first message:
```text theme={null}
https://wa.me/441234567890?text=Hi%20I%27m%20interested%20in%20%5BSPRING_LAUNCH%5D
```
Flowella can parse the pre-filled message for tracking codes and write them to HubSpot. The convention we recommend:
* Use a **bracketed keyword** the user is unlikely to type by accident, e.g. `[SPRING_LAUNCH]` or `[NEWSLETTER_JUL]`.
* Wrap the keyword in markers so the parsing is unambiguous.
* Keep the keyword short and human-readable so the pre-filled message still looks natural.
The extracted code lands in the HubSpot contact's `whatsapp_entry_source` property (or a custom property you specify in **Flowella → Settings → HubSpot**).
### Generating the links per campaign
A practical pattern: in your HubSpot campaign tool or marketing spreadsheet, build a small lookup of campaign → entry code, and generate one `wa.me` URL per campaign. Use a URL shortener or the campaign's tracking URL if you want a tidier link on email and ad creatives.
## Pattern 3: Form-submission UTMs
When a HubSpot form submission triggers a WhatsApp workflow, the standard HubSpot UTM properties (`hs_analytics_first_url`, `hs_analytics_source`, `hs_analytics_source_data_1` etc.) are already on the contact. Flowella reads these via the HubSpot integration and surfaces them in the conversation context.
This is the cleanest pattern when WhatsApp is a **follow-up** channel: the customer originally arrived via a UTM-tagged URL, submitted a form, and Flowella triggers a WhatsApp Flow that fills in the gaps. The UTM attribution is preserved end to end without anything specific to WhatsApp.
## Building HubSpot reports against this data
Once the attribution lands on the contact, you can build standard HubSpot reports against it:
* **Contacts by `whatsapp_entry_source`** — which campaigns drove WhatsApp leads
* **Deals → first source = WhatsApp** — revenue attributable to WhatsApp-originated contacts
* **Workflow performance by source** — which campaigns produced the highest reply / conversion rates inside the WhatsApp Flow
See [Reporting and dashboards](/hubspot/reporting-and-dashboards) for the report patterns we recommend setting up.
## What attribution does Flowella write to HubSpot?
By default, Flowella writes the following properties on each contact during WhatsApp activity:
| Property | Type | When written |
| ----------------------------- | --------- | ------------------------------------------------------------ |
| `whatsapp_opted_in` | Boolean | When the contact gives WhatsApp consent |
| `whatsapp_first_message_at` | Timestamp | When Flowella first sees an inbound message |
| `whatsapp_last_message_at` | Timestamp | Updated on every inbound message |
| `whatsapp_entry_source` | String | First inbound message's parsed source code or `ctwa_clid` |
| `whatsapp_campaign_id` | String | The Flowella campaign ID for the conversation, if applicable |
| `whatsapp_template_last_sent` | String | The most recent template sent to the contact |
You can map additional WhatsApp data to custom HubSpot properties in **Flowella → Settings → HubSpot → Field mapping**.
## Common gotchas
Not every WhatsApp inbound carries a `ctwa_clid`. Only those that came from a Facebook/Instagram CTWA ad do. Direct messages (where the customer typed your number into WhatsApp manually) won't have this value, which is correct — there's no ad to attribute them to.
The pre-filled message is just a default. Some users delete it before sending, others edit it. Don't rely on it for critical routing logic.
For robust attribution, prefer `ctwa_clid` (which the user can't strip) over `text` pre-fill parsing (which they can).
A customer who clicked a Facebook CTWA ad on Tuesday, didn't message, then opened the same ad on Wednesday and did message, will have the Wednesday click's `ctwa_clid` in the WhatsApp metadata. HubSpot's standard first-touch / last-touch attribution still works on the underlying UTMs if the customer also visited your website in between.
## Related guides
* [CTWA Ads](/campaigns/click-to-whatsapp-ads) — full setup including Conversions API
* [Reporting and dashboards](/hubspot/reporting-and-dashboards) — turning attribution data into reports
* [Workflow Actions](/hubspot/workflow-actions) — the workflow actions that fire when an inbound message arrives
# HubSpot Workflow Triggers and Actions in Flowella
Source: https://knowledge.flowella.io/hubspot/workflow-actions
Configure Flowella's HubSpot workflow triggers and actions: Form Completed, Text Reply, WhatsApp sends, AI Document Reader, Generate Document, and AI 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 | `formName`, `source` |
| **Text Reply** | Inbound | A contact sends a free-text reply in a Flowella-managed conversation | Route on keywords, capture opt-in, detect intent | `phone`, `message`, `responseTimeSeconds` |
| **Message Read** | Outbound | A contact opens a WhatsApp message you sent | Follow up only once the message has been seen | `phone`, `messageType`, `timeToReadSeconds` |
| **Message Sent** | Outbound | A WhatsApp message is dispatched to a contact via Flowella | Log outbound activity, start a follow-up timer | `phone`, `deliveryStatus`, `templateName` |
### Filtering on event properties
Each trigger exposes the properties declared on its timeline event schema. You can use them as filter conditions on the trigger itself, or on any HubSpot active list, report, or **Delay until event occurs** step.
`messageType` on Message Read is an enum with the values `TEXT`, `IMAGE`, `AUDIO`, `VIDEO`, `DOCUMENT`, `TEMPLATE`, `SYSTEM`, and `OTHER`. Filters like `messageType = TEMPLATE` are stable and case-insensitive. Common patterns:
* **`templateName = flowella_form_reminder`** on Message Sent to enrol contacts who received a specific template.
* **`messageType = TEMPLATE`** on Message Read to isolate read receipts of template sends.
* **Message contains "cancel"** on Text Reply to build a cancellation intent workflow.
Direction is fixed by trigger type rather than by a filterable property: Message Sent and Message Read are always outbound, and Text Reply is always inbound. Pick the trigger that matches the direction you want.
See [Contact activity](/hubspot/contact-activity#event-properties-for-filtering) for the full property reference.
### 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 six 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.
**Duplicate template send suppression.** If the same template has already been sent to the same phone number inside Flowella's dedupe window (typically when two HubSpot contacts share a phone number and enrol within seconds of each other), Flowella suppresses the second send and completes the HubSpot workflow action immediately as a failure with reason `DUPLICATE_TEMPLATE_SEND_SUPPRESSED`. The enrolled contact moves on to the next step straight away instead of sitting on the action for around an hour until HubSpot's callback timeout. This is an intentional guard, not a delivery failure — the original template did send to the shared number. See [HubSpot sync failures](/troubleshooting/hubspot-sync-failures#template-send-suppressed-as-duplicate) if you need to tell it apart from a genuine send failure.
### 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.
### Failure reason on the enrollment history
When a **Send WhatsApp Template**, **Send WhatsApp Message**, or **Send WhatsApp Reply** action fails, HubSpot's contact enrollment history now shows the specific Flowella failure reason on the row instead of a blank **Failed**. Each failed row carries both a human-readable message and an error code you can filter or search on.
Common error codes:
| Error code | Meaning |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `BODY_PARAMETER_COUNT_MISMATCH` | The number of mapped template variables does not match the variables defined on the template. |
| `CONTACT_PHONE_MISSING` | The recipient phone number property is empty on the contact. |
| `CONTACT_PHONE_INVALID` | The recipient phone number is not in a valid E.164 format. |
| `TEMPLATE_NOT_FOUND` | The selected WhatsApp template no longer exists in Flowella or has been deleted. |
| `TEMPLATE_WABA_MISMATCH` | The selected template belongs to a different WhatsApp Business Account than the channel the action is sending from. |
| `FAILED` | Any other send failure. The message text on the row still names the underlying cause. |
See [HubSpot sync failures](/troubleshooting/hubspot-sync-failures#send-action-failure-codes) for how to resolve each one.
### 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
### AI Document Reader
This action reads a PDF or image, extracts the values you ask for, and writes them into HubSpot contact properties. Use it to process documents your contacts send you, such as an ID uploaded through a HubSpot form, a signed agreement stored in HubSpot files, or a document linked from another system.
| Field | Description |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Document source**\*(required)\* | Where the document lives. Accepts an `https://` link, a HubSpot file ID, or the name of a contact property that holds a file. Supports object property mapping. |
| **Field map JSON**\*(required)\* | A JSON array of up to 40 entries. Each entry pairs a value to extract from the document with the internal name of the HubSpot contact property to write it to. |
| **Extraction instructions** | Optional free-text hints for the extraction, such as where a value appears on the document or how to interpret ambiguous fields. |
| **Clear HubSpot properties when empty** | No longer used. Every mapped property is always written, and fields missing from the document are cleared. Leaving it checked or unchecked makes no difference. |
A field map looks like this:
```json theme={null}
[
{ "extract": "passport_number", "hubspot": "passport_number" },
{ "extract": "date_of_birth", "hubspot": "date_of_birth" },
{ "extract": "full_name", "hubspot": "firstname" }
]
```
**Document source options:**
* **Link**: a direct `https://` URL to the file. HubSpot file preview links (the address shown when you open a file inside HubSpot) are resolved to the underlying file automatically.
* **HubSpot file**: the numeric ID of a file in your HubSpot file manager.
* **Contact file property**: the internal name of a contact property that holds a file, including file properties filled by HubSpot form uploads.
**Supported file types:** PDF, JPEG, PNG, and WebP. HEIC and HEIF photos (the format iPhones use by default) are converted to JPEG automatically before extraction, so contacts can upload a photo straight from their camera roll.
**How properties are written:**
* Every property in your field map is written on each run, blanks included. If a field stops appearing on a document, the matching contact property is cleared rather than left holding an old value.
* If the field map points at a contact property that does not exist in your HubSpot portal, Flowella skips that name and saves the rest, so one mistyped property name no longer loses the whole extract. The skipped names are reported to Flowella engineering.
On success, the enrollment history shows the **Properties written** and **Page count** outputs, which later workflow steps can also use as data tokens.
**Error codes:**
| Error code | Meaning |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DOCUMENT_DOWNLOAD_FAILED` | The document could not be fetched. Flowella retries up to three times before reporting this, so short-lived outages at HubSpot or the file host do not trigger it. |
| `DOCUMENT_UNSUPPORTED_TYPE` | The file is a type Flowella cannot read. The failure message includes the detected type, for example `DOCUMENT_UNSUPPORTED_TYPE:application/zip`. |
| `DOCUMENT_SOURCE_NOT_A_FILE` | The document source points at something that is not a file, such as a web page. Check the workflow step's source configuration. |
### Generate Document
This action fills a Flowella PDF document template with the enrolled contact's HubSpot properties and saves the finished PDF to your HubSpot files. Use it to produce personalised letters, confirmations, summaries, or any other per-contact PDF as part of a workflow.
Templates are created on the [Settings → Document templates](/settings/document-templates) screen in Flowella. Copy the template ID from that screen into the action.
| Field | Description |
| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Document template ID**\*(required)\* | The ID of the Flowella document template to render, copied from **Settings → Document templates**. |
| **Output filename** | Optional filename for the generated PDF. Defaults to a name based on the template. |
| **HubSpot file property** | Optional contact property to store the generated file's HubSpot file ID against the contact. |
The action returns two outputs that later workflow steps can use as data tokens:
* **File URL**: the URL of the generated PDF in HubSpot files. Map it into a **Send WhatsApp Message** document send, an email, or a CRM property.
* **HubSpot file ID**: the file's ID in your HubSpot file manager.
***
## 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.
# Abandoned Cart Recovery
Source: https://knowledge.flowella.io/hubspot/workflows/abandoned-cart-recovery
Bring shoppers back over WhatsApp with a helpful reminder, exit on purchase, a support-first rescue Flow, and a controlled incentive only when needed.
When a checkout stalls, this workflow sends a helpful reminder, branches on purchase status, and offers support or an incentive only when the first nudge does not convert, recovering revenue without email fatigue or leaking discounts to people who would have bought anyway.
## At a glance
| | |
| ----------------- | ------------------------------ |
| **Trigger** | Checkout abandoned |
| **Channels** | WhatsApp |
| **Templates** | 3 (reminder, help Flow, final) |
| **Typical cycle** | 24 to 48 hours |
| **Platforms** | HubSpot, Stripe |
## What this workflow does
Shortly after a cart is abandoned, the shopper receives a reminder showing the reserved items. If they still have not bought, a support-first Flow asks what is holding them back, so an objection can be resolved by a human rather than papered over with a discount. A controlled incentive is offered only as a later step, and the workflow exits the moment Stripe confirms a purchase.
## What you will need
* An abandoned-checkout signal synced to HubSpot
* WhatsApp templates for the reminder, a help Flow, and a final message
* Stripe connected, with a webhook on successful purchase
* An optional, capped discount code for the incentive step
## Workflow steps
1. **Trigger** checkout abandoned event.
2. **Send reminder (around 1 hour)** show the reserved items and a complete-order link. Hold the incentive back at this stage.
3. **Wait and check purchase** if Stripe confirms a purchase, exit immediately.
4. **Send help Flow** ask what stopped them (price, delivery, payment, a question) and route objections to a human where useful.
5. **Controlled incentive** only if still unconverted, send a capped, time-limited code.
6. **Final message** one last reminder, then end. Exit on purchase at any point.
## WhatsApp templates
* `tmpl_cart_reminder` cart reminder with image header and offer strip (Marketing category)
* `tmpl_cart_help` what-is-holding-you-back Flow (Utility category)
* Final reminder template
## Tips and gotchas
Lead with help, not a discount. A support-first rescue protects margin by reserving incentives for the carts that genuinely need one, which keeps discount leakage down.
# Appointment and Meeting Reminders
Source: https://knowledge.flowella.io/hubspot/workflows/appointment-reminders
Send a 24-hour reminder before appointments with a one-tap confirm, reschedule, or cancel form, plus a morning-of reminder if there is no response.
Twenty-four hours before a scheduled appointment or meeting, the contact receives a WhatsApp message with the details and a short form to confirm, reschedule, or cancel. The workflow updates the record, notifies the right person, and sends a second reminder on the morning of the appointment if there is no response. It also handles pre-visit requirements such as dietary or accessibility needs.
## At a glance
| | |
| ------------- | --------------------------------------- |
| **Trigger** | Meeting or appointment date approaching |
| **Channels** | WhatsApp |
| **Templates** | Confirmation Flow plus reminder |
| **Platforms** | HubSpot |
## What this workflow does
The contact gets a confirmation request the day before. If they confirm, an optional same-day reminder follows. If they need to reschedule or cancel, a task is created for the host with the reason or preferred time. Where the appointment involves a visit, the same form can collect special requirements that are written back to HubSpot as structured data, so the team can prepare in advance. No response triggers a lighter morning-of reminder.
## What you will need
* A WhatsApp Flow template for confirm, reschedule, or cancel (with optional requirements fields)
* A HubSpot contact or meeting property holding the appointment date and time
* The contact's WhatsApp number in international format
## Workflow steps
1. **Trigger** meeting created in HubSpot's meetings tool, a custom date property, or enrolment from a booking workflow.
2. **Delay until 24 hours before** pause the workflow until the day before the appointment.
3. **Send confirmation** personalised with first name, date, time, and host or location.
4. **Wait for completion** delay until Form Completed, up to 20 hours.
5. **Branch, completed:**
* **Confirmed** set Meeting Confirmed to Yes, send confirmation, optionally add a reminder 2 hours before.
* **Reschedule** acknowledge, create a task for the host with the preferred time, notify internally.
* **Cancel** acknowledge, create a task with the reason, optionally enrol in re-engagement.
6. **Branch, no response** send a short morning-of reminder, wait up to 2 hours for a reply, then confirm, create a task, or proceed as scheduled.
## Tips and gotchas
For multi-person meetings, enrol all associated contacts so each gets their own confirmation. For recurring appointments, enable re-enrolment so the workflow runs each cycle.
* For restaurants and clinics, keep any requirements form to three to five fields and make sure the team can see the collected properties before the visit.
# Authentication and OTP
Source: https://knowledge.flowella.io/hubspot/workflows/authentication-otp
Send one-time passwords and login approvals over WhatsApp, with single-use codes, a retry path, a fail-closed lockout, and audit logging in HubSpot.
WhatsApp puts one-time passwords where people are already looking on mobile, cutting email delays and failed verifications. This workflow sends, verifies, and on failure retries or locks out, while keeping the CRM informed without turning security into a support ticket.
## At a glance
| | |
| ----------------- | --------------------------------- |
| **Trigger** | Login or sensitive action request |
| **Channels** | WhatsApp OTP |
| **Templates** | 3 (code, resend, lockout) |
| **Typical cycle** | 30 to 90 seconds |
| **Platforms** | HubSpot |
## What this workflow does
When a user requests a login or a step-up verification, an Authentication-category template delivers a single-use code with a copy-code button. A correct code passes. An incorrect entry triggers a fresh code and invalidates the old one. After the maximum number of attempts, the account is paused for a set period with a support hand-off, and every outcome is logged for investigation.
## What you will need
* Authentication-category WhatsApp templates with an OTP block and copy-code button
* A code generator (your auth service or HubSpot) feeding the code at send time
* Properties to log attempts, outcomes, and lockouts for audit
* A support hand-off path for false positives
## Workflow steps
1. **Trigger** a login or action request from your application.
2. **Send code** deliver `tmpl_otp_code` with a single-use code that expires in a few minutes.
3. **Verify** check the entered code against your auth service.
4. **Branch, valid** mark verified, log the success, and return the user to their action.
5. **Branch, invalid** send `tmpl_otp_retry` with a fresh code and invalidate the previous one. Rate-limit retries.
6. **Lockout (fail closed)** after the maximum attempts, send `tmpl_otp_locked`, pause sign-in for the set period, and offer support. Send an unlock confirmation when the window passes.
7. **Audit** log every send, attempt, and lockout against the contact.
## WhatsApp templates
* `tmpl_otp_code` verification code with copy-code button (Authentication category)
* `tmpl_otp_retry` fresh code after a failed attempt (Authentication category)
* `tmpl_otp_locked` lockout and unlock messaging (Authentication category)
## Tips and gotchas
Never reuse codes, and never expose account details in an Authentication template. Rate-limit retries and keep support scripts ready for false positives. OTP should be fast for the real user and boringly strict for everyone else.
# Contact Data Refresh
Source: https://knowledge.flowella.io/hubspot/workflows/contact-data-refresh
Ask contacts to confirm the details you already hold, collect corrections in-thread, and write clean properties back to HubSpot with a clear freshness flag.
Stale CRM data quietly erodes everything built on top of it. This workflow asks contacts to confirm the details you already hold, collects corrections in the same thread, and writes clean properties back to HubSpot, then sets a freshness flag so you know the record is current.
## At a glance
| | |
| ----------------- | ----------------------------------------- |
| **Trigger** | Stale-data segment or annual refresh date |
| **Channels** | WhatsApp |
| **Templates** | 3 (confirm Flow, nudge, thank-you) |
| **Typical cycle** | 1 to 3 days |
| **Platforms** | HubSpot |
## What this workflow does
Contacts in a stale-data segment receive a confirmation Flow showing the email, mobile, and address on file. They either confirm the details are correct or update the ones that have changed, with corrections syncing to HubSpot on submit. A single nudge follows after a week of no response, and the freshness flag (last-confirmed date) is set either way so you can target the next refresh accurately.
## What you will need
* A WhatsApp Flow template for confirming and correcting contact details
* A HubSpot active list of stale records (for example, last confirmed more than 12 months ago)
* A last-confirmed date property to act as the freshness flag
## Workflow steps
1. **Trigger** list membership for the stale-data segment, or an annual refresh date property.
2. **Send confirm Flow** show the details on file and offer one-tap confirm or per-field update.
3. **Wait for completion** delay until Form Completed, up to 7 days.
4. **Branch, confirmed or corrected** write any corrections, set the last-confirmed date to today, send a brief thank-you.
5. **Branch, no response at 7 days** send a single friendly nudge noting it takes under a minute. If still no response, leave the freshness flag unset so the record stays in the next refresh.
## WhatsApp templates
* `tmpl_data_confirm` confirm-your-details Flow (Utility category)
* `tmpl_data_nudge` friendly reminder after 7 days
* Thank-you confirmation message
## Tips and gotchas
One reminder is enough. Data refresh is a low-stakes ask, so a single nudge keeps reply rates healthy without nagging. The freshness flag does the rest by scoping who gets asked next time.
# Customer Onboarding
Source: https://knowledge.flowella.io/hubspot/workflows/customer-onboarding
Welcome new customers over WhatsApp, guide them to first value with milestone prompts, rescue stalled setups, and keep onboarding status synced to HubSpot.
When a new customer signs up or a deal closes, this workflow welcomes them in WhatsApp and guides them to first value with milestone prompts, setup nudges, and a support rescue path, keeping their onboarding status updated in HubSpot throughout.
## At a glance
| | |
| ------------- | ------------------------------------------- |
| **Trigger** | Deal closed won or lifecycle stage Customer |
| **Channels** | WhatsApp |
| **Templates** | Welcome plus onboarding Flow(s) |
| **Platforms** | HubSpot |
## What this workflow does
The customer receives a welcome message, then a structured onboarding sequence broken into milestones. The workflow tracks completion, sends reminders for incomplete steps, and routes data to the right teams. Customers who get stuck are offered a Breeze Customer Agent for real-time help in WhatsApp.
## What you will need
* One or more WhatsApp Flow templates for onboarding steps
* An onboarding status property (Not Started, In Progress, Completed, Stalled)
* Properties to store the collected data
* The customer's WhatsApp number in international format
## Workflow steps
1. **Trigger** deal stage Closed Won, lifecycle stage Customer, or enrolment from a sales workflow.
2. **Send welcome** a warm message, set status to In Progress, add a short delay so the welcome lands before the first form.
3. **Send onboarding Flow** for multi-step onboarding, send the first form here.
4. **Wait for completion** delay until Form Completed, up to 48 hours.
5. **Branch, completed** update properties, set status to Completed, confirm, notify the account team, and optionally assign a Customer Agent for ongoing support.
6. **Branch, not completed** remind and re-send, wait another 48 hours, then offer AI help, set status to Stalled, and create a task for the account manager.
7. **Repeat per milestone** for multi-step onboarding, repeat send, wait, branch, tracking progress with a step property (for example, 1 of 3 complete).
## Tips and gotchas
Break onboarding into milestones rather than one long form. Each completed step is a small win that keeps momentum and gives you a clear place to rescue a stall.
# Donation Campaigns
Source: https://knowledge.flowella.io/hubspot/workflows/donation-campaigns
Run video-led WhatsApp donation appeals from HubSpot, with an in-chat donation Flow, and exit the moment a supporter gives so you never ask twice.
Lead with story, not the ask. This workflow runs a video-led donation appeal over WhatsApp: a short founder video lands the why, an in-chat donation Flow handles the gift, and the moment payment clears the workflow stops asking and says thank you.
## At a glance
| | |
| ----------------- | ---------------------------------------- |
| **Trigger** | Supporter joins a campaign list |
| **Channels** | WhatsApp video |
| **Templates** | 3 (video hook, donation Flow, thank-you) |
| **Typical cycle** | 10 to 14 days |
| **Platforms** | HubSpot, Stripe |
## What this workflow does
Supporters on the campaign list receive a founder video that makes the case in under two minutes, followed by an in-chat donation Flow with amount chips, one-off or monthly options, and Gift Aid. When Stripe confirms the payment, the supporter exits the appeal track immediately and receives a thank-you video. Supporters who have not given receive a fresh angle every few days until the campaign ends.
## What you will need
* A WhatsApp video template, an in-chat donation Flow, and a thank-you template
* Stripe connected for in-chat payment, with a webhook on successful payment
* A HubSpot campaign list and a donation status property
* Gift Aid handling if you are a UK charity
## Workflow steps
1. **Trigger** list membership when a supporter joins the campaign.
2. **Send founder video** the day-0 hook with a Donate now call to action.
3. **Send donation Flow** open the in-chat Flow with amount chips and frequency options.
4. **Wait for payment** delay until the donation status is set, branching on the Stripe webhook.
5. **Branch, donated** send the thank-you video, set status to Donated, and exit the appeal track. Never send another donate-now in this campaign.
6. **Branch, not yet** every few days send a fresh video angle until the campaign close date, then end.
## WhatsApp templates
* `tmpl_donate_video_01` founder video hook (Marketing category)
* `tmpl_donate_flow` in-chat donation Flow with amounts and Gift Aid (Utility category)
* Thank-you video template sent on payment
## Tips and gotchas
Exit on the first donation. A second donate-now to someone who has already given is the fastest way to lose a supporter's trust and their next gift.
# Event and Webinar Reminders
Source: https://knowledge.flowella.io/hubspot/workflows/event-webinar-reminders
Run the full event lifecycle in WhatsApp: registration, timed reminders, day-of messages, attendance branching, replay follow-up, and HubSpot scoring.
When a contact shows interest in an event or webinar, this workflow registers them in WhatsApp, sends timed reminders, branches on attendance, and follows up afterwards (including a replay link for no-shows and a feedback form for attendees). HubSpot scoring records engagement throughout.
## At a glance
| | |
| ------------- | ---------------------------------------- |
| **Trigger** | Web form, ad, QR code, or list enrolment |
| **Channels** | WhatsApp |
| **Templates** | Registration Flow plus feedback Flow |
| **Platforms** | HubSpot, Calendly (optional) |
## What this workflow does
The contact receives a registration Flow capturing attendance, session choices, and any dietary needs. Confirmed registrants move into a reminder sequence (one week before, one day before, and the morning of). After the event, attendees receive a feedback form with score-based branching, while no-shows receive a replay link and an invitation to the next session.
## What you will need
* A WhatsApp Flow template for registration
* A second Flow template for post-event feedback
* HubSpot properties for registration status, event name, and event date
* An attendance property fed from your webinar or events platform
## Workflow steps
1. **Trigger** web form submission, Click-to-WhatsApp ad or QR (Text Reply), list enrolment for invitees, or manual enrolment for VIPs.
2. **Send registration form** personalised with first name, event name, date, and location or link.
3. **Branch on registration:** Confirmed sets status Registered and enters the reminder track. Tentative gets a holding message and a re-confirmation Flow. Declined is acknowledged. No response gets a nudge and a re-send.
4. **Pre-event reminders** one week before (details), one day before (direct reminder or re-confirmation), and the morning of (final message with the join link).
5. **Attendance branch** after the event, attendees receive the feedback Flow. No-shows receive a replay link and a next-event invitation.
6. **Post-event feedback** wait up to 7 days, then branch on score: high (review or share link and early access), mid (thank and log), low (apologise and create a task).
## Tips and gotchas
For webinars, send the join link in the morning-of message rather than at registration, so it is easy to find when it matters.
# Hospitality Feedback
Source: https://knowledge.flowella.io/hubspot/workflows/hospitality-feedback
Catch a bad night before it reaches Google: WhatsApp feedback after a stay or visit, promoter review prompts, detractor recovery, and cohort tagging.
For hotels, restaurants, and venues, this workflow sends a short feedback request shortly after a stay or visit, invites happy guests to leave a public review, and quietly routes unhappy guests into recovery before a poor experience becomes a public rating.
## At a glance
| | |
| ------------- | -------------------------------------- |
| **Trigger** | Visit or stay completed |
| **Channels** | WhatsApp |
| **Templates** | Feedback Flow plus detractor follow-up |
| **Platforms** | HubSpot |
## What this workflow does
A couple of hours after a visit (or the morning after checkout for hotels), the guest receives a one or two field rating form. Promoters are thanked and sent a review link while the experience is fresh. Passives are thanked and their feedback logged. Detractors get an apology, a follow-up form to capture what went wrong, and a service recovery action. Cohort tags let you spot patterns by venue, shift, or season.
## What you will need
* A WhatsApp Flow template for the feedback form (rating 0 to 10, optional comment)
* A second Flow template for detractor follow-up
* A visit or checkout property, and your public review page URL
* A feedback segment property and cohort tags
## Workflow steps
1. **Trigger** deal stage Completed or Visited, a date property after the visit, or enrolment from a booking confirmation workflow.
2. **Timing delay** 2 hours after a restaurant booking, or the morning after a hotel checkout.
3. **Send feedback form** personalised with first name and venue or visit date.
4. **Wait for completion** delay until Form Completed, up to 48 hours.
5. **Branch on score:**
* **Promoters (9 to 10)** thank and send the review link, set segment to Promoter, optionally enrol in loyalty.
* **Passives (6 to 8)** thank, set segment to Passive, create an internal task if specific feedback was left.
* **Detractors (0 to 5)** apologise, send the detractor Flow, branch on the chosen recovery (discount, manager callback, or nothing needed), set segment to Detractor, and open a service ticket.
6. **Branch, not completed** one gentle nudge after 48 hours, then end.
## Tips and gotchas
Keep the first form to one or two fields and send the review link immediately after a high score. Cohort tags by shift or venue turn individual feedback into operational insight.
# Job Applicant Status
Source: https://knowledge.flowella.io/hubspot/workflows/job-applicant-status
Keep candidates informed over WhatsApp with application confirmations, stage updates, interview booking, offers or regrets, and hiring outcome tracking.
Silence is what damages employer brand. This workflow keeps candidates informed at every stage over WhatsApp, from application confirmation through interview booking to a clear offer or a kind regret, with each step driven by your ATS or HubSpot.
## At a glance
| | |
| ----------------- | -------------------------------------- |
| **Trigger** | ATS or pipeline stage change |
| **Channels** | WhatsApp |
| **Templates** | 3 (received, interview Flow, decision) |
| **Typical cycle** | Per pipeline |
| **Platforms** | HubSpot |
## What this workflow does
When a candidate applies, they receive an acknowledgement with an expected timeframe. As they move through the pipeline, stage updates keep them informed. Shortlisted candidates get an interview booking Flow. At the end, the workflow sends either an offer message or a considerate regret, and records the hiring outcome so reporting stays clean.
## What you will need
* Candidate stage synced from your ATS to HubSpot (or HubSpot used as the pipeline)
* WhatsApp templates for application received, an interview booking Flow, and decision messages
* Properties for role, stage, and outcome
## Workflow steps
1. **Trigger** ATS or pipeline stage change.
2. **Application received** acknowledge the application with the role title and an expected review window.
3. **Stage updates** send a short update as the candidate advances.
4. **Shortlisted** send the interview booking Flow with available slots.
5. **Decision branch:**
* **Offer** send the offer message and next steps.
* **Regret** send a considerate decline, optionally inviting them to stay in the talent pool.
6. **Record outcome** write the final outcome for hiring reporting.
## WhatsApp templates
* `tmpl_appl_received` application received (Utility category)
* `tmpl_appl_book` interview slot booking Flow (Utility category)
* Decision template for offer or regret
## Tips and gotchas
Send a kind regret, not silence. A prompt, respectful decline protects your employer brand and keeps strong candidates open to future roles.
# KYC Onboarding
Source: https://knowledge.flowella.io/hubspot/workflows/kyc-onboarding
Collect KYC documents over WhatsApp with structured requests, missing-file nudges, verification branches, and manual review only for the exceptions.
This workflow completes know-your-customer onboarding faster by requesting documents over WhatsApp, nudging for anything missing, branching on verification status, and routing to manual review only when a case needs human judgement.
## At a glance
| | |
| ------------- | ---------------------------------------- |
| **Trigger** | New regulated customer or account opened |
| **Channels** | WhatsApp |
| **Templates** | Document request Flow plus reminders |
| **Platforms** | HubSpot |
## What this workflow does
New customers receive a structured request for the identification and compliance information you need. The workflow tracks what has been supplied, nudges for missing files, and branches on the verification result: clean cases pass automatically, while flagged or incomplete cases go to manual review. A Breeze Customer Agent can help customers who get stuck.
## What you will need
* One or more WhatsApp Flow templates for KYC data collection
* A verification status property (for example, Pending, Verified, Manual Review, Failed)
* Properties to store the collected fields
* A documented data processing agreement covering the Flowella to HubSpot data flow
## Workflow steps
1. **Trigger** account opened, deal stage change, or enrolment from a sign-up workflow.
2. **Send welcome and first request** explain what is needed and why, then send the first KYC Flow.
3. **Wait for completion** delay until Form Completed, up to 48 hours.
4. **Branch, submitted** run verification. Clean result sets status to Verified and continues onboarding. Flagged result sets status to Manual Review and creates a task for the compliance team.
5. **Branch, missing files** send a missing-file nudge naming exactly what is outstanding, wait, then escalate to a Customer Agent or a manual review task.
6. **Manual review only for exceptions** keep human review for the cases that genuinely need it, rather than every applicant.
## Tips and gotchas
For highly sensitive data such as full identification numbers or document images, direct customers to a secure portal rather than collecting it in the WhatsApp thread, and make sure your data processing agreements cover the full flow.
# Lead Capture and Qualification
Source: https://knowledge.flowella.io/hubspot/workflows/lead-capture-qualify
Send a short qualification form to new leads over WhatsApp, score the responses, and route high-fit leads to sales while nurturing the rest.
When a new lead arrives from a Click-to-WhatsApp ad, QR code, website form, or direct message, this workflow sends a short qualification form, writes the answers back to HubSpot as structured properties, then scores and routes the lead automatically.
## At a glance
| | |
| ------------- | --------------------------------------------- |
| **Trigger** | New lead from ad, form, QR, or direct message |
| **Channels** | WhatsApp |
| **Templates** | Qualification Flow plus follow-up |
| **Platforms** | HubSpot |
## What this workflow does
The lead receives a four or five question form in WhatsApp covering budget, timeline, company size, and primary need. Responses become contact properties, and the workflow tiers each lead: high-value leads go straight to a sales rep with a deal and an owner, mid-value leads enter a nurture sequence, and early-stage leads are handed to a Breeze Customer Agent for AI engagement.
## What you will need
* A WhatsApp Flow template for lead qualification
* Lead scoring in HubSpot (optional but recommended)
* Sales users configured for owner assignment
* A Breeze Customer Agent (optional, for AI handoff)
## Workflow steps
1. **Trigger** Flowella: Form Completed from a welcome Flow, a lifecycle stage change to Lead, Flowella: Text Reply for direct enquiries, or enrolment once a WhatsApp number is known.
2. **Send qualification form** personalised with first name and, where known, the product or service enquired about.
3. **Wait for completion** delay until Form Completed, up to 24 hours.
4. **Branch, completed:**
* **Tier 1, high value** budget over the high threshold and an immediate or near-term timeline, set lifecycle to SQL, create a deal, assign an owner, notify the rep, and create a task to make contact within the hour.
* **Tier 2, mid value** mid-range budget or a three-month timeline, set lifecycle to MQL and enrol in nurture.
* **Tier 3, early stage** low budget or "just exploring", assign to a Breeze Customer Agent and set Lead Status to AI Engaged.
5. **Branch, not completed** send a follow-up offering to chat instead, wait up to 48 hours for a reply, then assign to a Customer Agent or set Lead Status to Unresponsive.
## Tips and gotchas
Keep the qualification form to four or five questions. Let the rep or AI agent gather the rest in conversation.
* Set tier thresholds as workflow properties so sales can tune them without rebuilding the branch.
# Meeting Booking Workflow
Source: https://knowledge.flowella.io/hubspot/workflows/meeting-booking
Send a calendar link the moment a lead asks for one, then nudge on WhatsApp until the meeting is booked, attended, and followed up.
Email is where calendar links go to die. This workflow sends a Calendly link over WhatsApp the second a lead submits a "Book a call" form, then keeps nudging until the meeting is booked, and exits automatically the moment Calendly confirms a booking.
## At a glance
| | |
| ----------------- | ------------------------------------------------ |
| **Trigger** | "Book a call" form completed |
| **Channels** | WhatsApp, with email fallback |
| **Templates** | 3 (calendar invite, slot picker Flow, reminders) |
| **Typical cycle** | 3 to 5 days |
| **Platforms** | HubSpot, Calendly |
## What this workflow does
When a lead asks to book a call, they receive a WhatsApp message with a calendar invite. If they do not book, a fresh nudge is sent every 48 hours (up to three times), each with a different angle rather than the same message repeated. The moment Calendly fires a booking webhook, the workflow exits the nudge loop. Confirmations go out 24 hours and 1 hour before the meeting to cut no-shows, and a post-meeting follow-up with notes and a next step is sent shortly after the call ends.
## What you will need
* A WhatsApp Flow or template set for the calendar invite, an in-chat slot picker, and reminders
* A Calendly account connected to HubSpot, with a webhook on booking events
* A HubSpot contact property holding the contact's WhatsApp number in international format
* Optionally, a lead score property if you want to gate nudges by intent
## Workflow steps
1. **Trigger** enrol on Flowella: Form Completed when the "Book a call" form is submitted.
2. **Send calendar invite** send the WhatsApp template with the Calendly link, personalised with first name, company, and the assigned rep.
3. **Wait for booking** delay until the Calendly booking property is set, up to 48 hours.
4. **Branch, no booking** send nudge 1, wait 48 hours, send nudge 2, wait 48 hours, send nudge 3. Each nudge offers a fresh set of slots. Exit the loop as soon as the booking webhook fires.
5. **Pre-meeting reminders** once booked, send a confirmation 24 hours before and a short reminder 1 hour before, each carrying the join link.
6. **Post-meeting follow-up** within 30 minutes of the meeting ending, send recording, notes, and a next-step call to action.
7. **Fallback** if the contact has no WhatsApp opt-in, branch to email for the calendar link.
## WhatsApp templates
* `tmpl_book_call_v3` calendar invite with image header (Marketing category)
* `tmpl_meeting_remind` in-chat slot picker Flow (Utility category)
* `tmpl_book_followup` reminders and 48-hour nudges (Marketing category)
## Tips and gotchas
Submit templates to Meta at least 48 hours ahead. Keep nudges more than 48 hours apart to protect your quality score, and clamp sends to working hours in the contact's timezone.
* Key the exit branch on the Calendly event ID, since Calendly retries webhooks on failure.
* Pass the UTM `source` property into the template so paid and inbound leads can be reported separately.
* Always include a global suppression branch for STOP and UNSUBSCRIBE replies.
# Subscription and Membership Renewals
Source: https://knowledge.flowella.io/hubspot/workflows/membership-renewals
Send renewal reminders 30 days out with a one-tap renew, handle update and cancel responses automatically, and run a win-back flow for waverers.
Thirty days before a subscription or membership is due, the member receives a WhatsApp message with their renewal details and a simple form: renew, update details, or considering cancelling. Confirmations are processed immediately, waverers get a retention offer, and non-responders receive two further reminders before expiry.
## At a glance
| | |
| ------------- | -------------------------------- |
| **Trigger** | Renewal date 30 days away |
| **Channels** | WhatsApp |
| **Templates** | Renewal Flow plus retention Flow |
| **Platforms** | HubSpot, Stripe |
## What this workflow does
The member gets a value recap and a one-tap renewal at 30 days. Those who renew are confirmed and their renewal date rolls forward. Those who want to update details are handed to a Customer Agent. Those considering cancellation receive a retention Flow with options you can actually fulfil. Non-responders get a lighter reminder at 14 days and a final heads-up at 7 days.
## What you will need
* A WhatsApp Flow template for renewal (renew, update, considering cancelling)
* A second Flow template for retention
* HubSpot properties for renewal date and subscription status
* The member's WhatsApp number in international format
## Workflow steps
1. **Trigger** contact date property when the renewal date is 30 days away. Enable re-enrolment so it runs each cycle.
2. **Send first reminder** personalised with name, plan, renewal date, and price.
3. **Wait for completion** delay until Form Completed, up to 14 days.
4. **Branch, completed:**
* **Renew** set status to Renewal Confirmed, confirm, roll the renewal date forward, end.
* **Update details** acknowledge, assign to a Customer Agent, create a verification task, re-send the renewal form afterwards.
* **Considering cancelling** send an empathetic message and the retention Flow, then branch on the chosen option (discount, pause, different plan, or speak to someone).
5. **No response at 14 days** send a lighter reminder noting no action is needed to continue, wait 7 days.
6. **Final reminder at 7 days** send a brief heads-up. If auto-renewal is on, confirm the renewal. If manual, create a task for the account team.
## Tips and gotchas
Frame renewal as the default where your terms allow auto-renewal. Offer only retention options you can fulfil, since a hollow offer damages trust more than a clean cancellation.
# NPS and CSAT Surveys
Source: https://knowledge.flowella.io/hubspot/workflows/nps-csat
Collect one-tap NPS or CSAT scores over WhatsApp, segment promoters, passives, and detractors, then route reviews or recovery automatically in HubSpot.
At a defined point in the journey (a resolved ticket, a delivered project, or a recurring schedule), the customer receives a simple NPS or CSAT question in WhatsApp. They tap a score and optionally add a comment, and the workflow segments them and takes a different automated action for each group.
## At a glance
| | |
| ------------- | --------------------------------------------- |
| **Trigger** | Ticket closed, project delivered, or schedule |
| **Channels** | WhatsApp |
| **Templates** | Survey Flow |
| **Platforms** | HubSpot |
## What this workflow does
The customer gets a one-tap score from 0 to 10 with an optional comment. Responses are stored as properties and segmented into Promoters, Passives, and Detractors, each with its own follow-up: promoters are invited to review or refer, passives are acknowledged and logged, and detractors trigger a service ticket and recovery. The survey date is recorded so contacts are not re-surveyed too soon.
## What you will need
* A WhatsApp Flow template for the survey (score 0 to 10, optional comment)
* Properties for the latest score, the segment, and the survey date
* Suppression rules for recent respondents, opt-outs, and active tickets
## Workflow steps
1. **Trigger** event-based (ticket closed, deal delivered) or time-based (survey date more than 90 days ago) with a known WhatsApp number.
2. **Send survey** personalised with first name and company.
3. **Wait for completion** delay until Form Completed, up to 7 days.
4. **Set survey date** update the survey date to today regardless of completion.
5. **Branch on score:**
* **Promoters (9 to 10)** thank, then after a short delay invite a review, testimonial, or referral.
* **Passives (7 to 8)** thank and log; if a comment was left, create a task for the account manager.
* **Detractors (0 to 6)** apologise, create a service ticket with the score and comment, notify internally, and optionally assign a Customer Agent.
6. **Branch, not completed** send one gentle reminder after 7 days, then end.
## Tips and gotchas
With scores in HubSpot properties you can report NPS over time, response rate, segment mix, and score by owner or lifecycle stage. Suppress anyone surveyed in the last 90 days to avoid fatigue.
# Order and Shipping Updates
Source: https://knowledge.flowella.io/hubspot/workflows/order-shipping-updates
Send order confirmation, dispatch, delay, delivery, and review prompts over WhatsApp so customers never have to ask where their order is.
This workflow sends proactive order and shipping updates from HubSpot so customers never need to open a "where is my order" ticket. It confirms the order, flags dispatch and delivery, handles delays and not-in scenarios, and finishes with a review prompt.
## At a glance
| | |
| ----------------- | ----------------------------------------------- |
| **Trigger** | Order placed |
| **Channels** | WhatsApp |
| **Templates** | 3 (out-for-delivery, preferences Flow, outcome) |
| **Typical cycle** | 2 to 7 days |
| **Platforms** | HubSpot |
## What this workflow does
As an order moves through fulfilment, the customer receives confirmation, dispatch, and an out-for-delivery message with the delivery window. If they will not be home, a preferences Flow lets them choose a safe place, a neighbour, or a new day. Delays are communicated proactively, and once delivered the customer gets a short review prompt. The hero moment is a same-day delivery message with in-chat preferences.
## What you will need
* Order and fulfilment status synced to HubSpot
* WhatsApp templates for out-for-delivery, a delivery preferences Flow, and outcome messages
* A carrier or location feed for the delivery window (optional)
## Workflow steps
1. **Trigger** order placed.
2. **Confirm order** send confirmation with the order reference.
3. **Dispatch and out for delivery** send `tmpl_order_dispatch` with the expected window and a Track parcel option.
4. **Branch, will not be in** open the preferences Flow to choose safe place, neighbour, or reschedule, and write the choice back.
5. **Delay branch** if fulfilment flags a delay, send a proactive delay message with a revised window.
6. **Delivered** confirm delivery and, after a short delay, send a review prompt.
## WhatsApp templates
* `tmpl_order_dispatch` out-for-delivery with location header and a Won't-be-in button (Utility category)
* `tmpl_order_not_in_flow` delivery preferences Flow (Utility category)
* Outcome template for confirm, delay, and delivered
## Tips and gotchas
Proactive delay messages cut the most tickets. Telling a customer about a slip before they notice it turns a complaint into reassurance.
# Re-engagement
Source: https://knowledge.flowella.io/hubspot/workflows/re-engagement
Wake dormant contacts with a WhatsApp preference prompt, branch on interest, snooze, or opt-out, and clean the HubSpot record automatically.
Contacts who have gone quiet receive a personalised WhatsApp message inviting them back, with a preference form that lets them tell you what they are interested in. Their response routes them into the right nurture path or cleanly out of it, and the HubSpot record is updated either way.
## At a glance
| | |
| ------------- | ------------------------------------------ |
| **Trigger** | Dormant-contact list or last-activity date |
| **Channels** | WhatsApp |
| **Templates** | Preference Flow (optionally an offer) |
| **Platforms** | HubSpot |
## What this workflow does
Dormant contacts receive either a preference form directly, or an offer first followed by the form if they engage. Re-engaged contacts have their interests and contact frequency updated and are enrolled in the matching nurture cadence. Contacts who read but do not act get one follow-up, then a status update. Contacts who do not read at all are flagged as unreachable for review or suppression.
## What you will need
* A WhatsApp Flow template for preferences (interests, frequency, categories)
* A HubSpot active list of dormant contacts with a known WhatsApp number
* A re-engagement status property
* An optional offer or discount code
## Workflow steps
1. **Trigger** list membership for dormant contacts, or a last-activity date property.
2. **Stagger sending** add a random delay (for example, 0 to 72 hours) to avoid rate limits on large lists.
3. **Send re-engagement message** either the preference Flow directly, or an offer first then the form on engagement.
4. **Wait for completion** delay until Form Completed, up to 7 days.
5. **Branch, re-engaged** update preferences, set status to Re-Engaged, thank, and enrol in the matching cadence (weekly, monthly, quarterly, or offers only).
6. **Branch, not completed** if read but not actioned, send one follow-up then set Unresponsive. If not read, set Unreachable and optionally try another channel.
## Tips and gotchas
Run a separate opt-out workflow on Flowella: Text Reply for keywords like stop, unsubscribe, or opt out. Update marketing status and confirm, so a re-engagement push never overrides someone's clear request to leave.
# Refer-a-Friend
Source: https://knowledge.flowella.io/hubspot/workflows/refer-a-friend
Turn happy customers into tracked referrals over WhatsApp, with unique links, friend signup checks, thank-you messages, and two-sided rewards.
When a customer hits a happy moment (an NPS promoter score or a milestone), this workflow sends their unique referral code, tracks the friend they invite, thanks the referrer, and rewards both sides when the referral converts.
## At a glance
| | |
| ----------------- | ---------------------------------- |
| **Trigger** | NPS promoter or customer milestone |
| **Channels** | WhatsApp |
| **Templates** | 3 (invite, referral Flow, reward) |
| **Typical cycle** | Ongoing |
| **Platforms** | HubSpot |
## What this workflow does
Eligible customers receive an invitation with a unique referral code and an in-chat referral Flow to nominate a friend. The nominated friend receives a personalised message with the code. When the friend signs up or buys, the workflow confirms the conversion, thanks the referrer, and triggers a two-sided reward, all tracked in HubSpot so the programme runs itself.
## What you will need
* WhatsApp templates for the invite, a referral Flow, and reward messaging
* A unique referral code per customer, stored on the contact
* Properties to track referrer, friend, and conversion status
* A reward fulfilment step (credit, discount, or Stripe coupon)
## Workflow steps
1. **Trigger** NPS promoter score, or a milestone such as a renewal or a delivered project.
2. **Send invite** share the unique code and a Refer someone call to action.
3. **Send referral Flow** capture the friend's name and mobile, plus an optional personal message.
4. **Invite the friend** send the friend a personalised message with the code.
5. **Check signup** when the friend converts, confirm the referral and record both sides.
6. **Reward both sides** thank the referrer and apply the two-sided reward.
## WhatsApp templates
* `tmpl_referral_invite` refer-a-friend invite with copy code (Marketing category)
* `tmpl_referral_flow` referral nomination Flow (Utility category)
* Reward and thank-you template
## Tips and gotchas
Trigger referrals off a genuine happy moment such as a promoter NPS score. A referral asked at the point of delight converts far better than a blanket campaign, and keeps blended acquisition cost down.
# Smart Review Triage
Source: https://knowledge.flowella.io/hubspot/workflows/smart-review-triage
Run a WhatsApp temperature check first, send public review links only to happy customers, and route unhappy ones into private recovery.
Asking every customer for a public review is a gamble. This workflow runs a quick temperature check in WhatsApp first, then sends a public review link only to customers who are clearly happy, while routing unhappy customers into private recovery before they post.
## At a glance
| | |
| ------------- | ---------------------------------------- |
| **Trigger** | Purchase, delivery, or service completed |
| **Channels** | WhatsApp |
| **Templates** | Temperature-check Flow plus follow-up |
| **Platforms** | HubSpot |
## What this workflow does
After a positive milestone, the customer gets a one-tap "how was it" question. Happy responses receive a public review link (Google, Trustpilot, or similar) while the goodwill is fresh. Unhappy responses skip the public ask entirely and instead open a private recovery conversation and a service task, so problems are fixed rather than published.
## What you will need
* A WhatsApp Flow template for the temperature check (happy or not)
* Your public review page URL
* A follow-up template for recovery, and a feedback segment property
## Workflow steps
1. **Trigger** deal or order marked complete, or enrolment from a fulfilment or service workflow.
2. **Send temperature check** a single one-tap question shortly after the milestone.
3. **Wait for completion** delay until Form Completed, up to 48 hours.
4. **Branch, happy** send the public review link with a short thank-you, set segment to Promoter.
5. **Branch, not happy** do not send a public link. Open a recovery message, create a service task, and optionally assign a Customer Agent. Set segment to Detractor.
6. **Branch, no response** one gentle nudge, then end.
## Tips and gotchas
Never send a public review link before the temperature check. The whole point is to earn reviews from happy customers and to catch unhappy ones privately first.
# Trial-to-Paid SaaS
Source: https://knowledge.flowella.io/hubspot/workflows/trial-to-paid-saas
Guide new trial users to activation over WhatsApp, branch on product usage, and send the upgrade call to action only once the account has seen value.
This workflow turns SaaS trials into paid customers by guiding new users toward activation over WhatsApp, branching by product usage, and sending the upgrade prompt only when the account has seen enough value to convert.
## At a glance
| | |
| ----------------- | -------------------------------------------- |
| **Trigger** | Trial started |
| **Channels** | WhatsApp |
| **Templates** | 3 (welcome, activation nudges, upgrade Flow) |
| **Typical cycle** | 7 to 14 days |
| **Platforms** | HubSpot, Stripe |
## What this workflow does
On day 0 the user gets a warm welcome and an offer of help. Over the trial, usage-based branching decides the messaging: activated users are nudged toward the upgrade, while stalled users get setup help and a rescue path. The upgrade Flow lets the user pick a plan and convert in chat through Stripe, with billing starting after the trial.
## What you will need
* A trial-started signal from your product, synced to a HubSpot property
* WhatsApp templates for welcome, activation help, and an upgrade Flow
* Stripe connected for in-chat plan selection
* An activation property (for example, a key action completed)
## Workflow steps
1. **Trigger** trial started property set in HubSpot.
2. **Day 0 welcome** confirm the trial length and offer help.
3. **Activation branch** if the activation event has fired, proceed toward upgrade. If not, send setup help and offer a Customer Agent.
4. **Upgrade Flow (around day 10)** send the plan picker, reassuring the user that their data and workflows are kept and billing starts after the trial.
5. **Convert** on plan selection through Stripe, send a confirmation and set the account to paid. Exit the nudge track.
6. **Trial ending, no upgrade** send a final value reminder before expiry, then move to a win-back cadence.
## WhatsApp templates
* `tmpl_trial_welcome` trial welcome with help options (Marketing category)
* Activation nudge template
* `tmpl_trial_help` upgrade Flow with plan picker (Utility category)
## Tips and gotchas
Gate the upgrade prompt on a real activation signal, not just elapsed days. Asking an inactive trial to pay converts poorly and burns goodwill.
# Web Contact Follow-up
Source: https://knowledge.flowella.io/hubspot/workflows/web-contact-followup
Ask one question on the website, then drip-feed the rest over WhatsApp so the CRM is enriched and the lead is qualified before an SDR ever calls.
Long web forms get abandoned. This workflow asks for the minimum on the site (typically two fields), then runs a five-day WhatsApp drip where each reply enriches the CRM and routes the next message. Forms get answered when they do not feel like forms.
## At a glance
| | |
| ----------------- | ------------------------------------ |
| **Trigger** | Web form with two fields |
| **Channels** | WhatsApp |
| **Templates** | 3 (welcome, use-case Flow, hand-off) |
| **Typical cycle** | 5 to 7 days |
| **Platforms** | HubSpot |
## What this workflow does
A short web form captures name and WhatsApp number. The contact then receives a friendly welcome, followed by a sequence of one-tap micro-questions spread over several days. Each answer writes straight to HubSpot and decides the next message. Once the contact's score clears the qualification threshold, the workflow hands off to an SDR with full context already in the record.
## What you will need
* A two-field HubSpot form on the website
* A WhatsApp welcome template, a use-case Flow, and a hand-off template
* Contact properties for each attribute you intend to enrich
* A qualification threshold (lead score or property combination)
## Workflow steps
1. **Trigger** Flowella: Form Completed on the two-field web form.
2. **Send welcome** confirm the enquiry and set expectations that a few quick questions will follow.
3. **Micro-question 1** send a one-tap Flow asking the primary use case. Write the answer and branch the next message.
4. **Drip the rest** over the following days, send further one-tap questions, each enriching one or two properties.
5. **Score and branch** when the score clears the threshold, set lifecycle to MQL and create a task for the SDR. Where it does not, continue nurturing or move to a lower-frequency cadence.
## WhatsApp templates
* `tmpl_web_welcome` welcome opener with image header (Marketing category)
* `tmpl_web_followup_q1` in-chat use-case Flow (Utility category)
* SDR hand-off template once qualified
## Tips and gotchas
Resist the urge to ask everything at once. One tap per message keeps reply rates high and steadily builds a richer record than a single long form ever would.
# Create a Meta business portfolio
Source: https://knowledge.flowella.io/meta/business-portfolio
Create a Meta business portfolio (formerly Business Manager) to hold your Pages, ad accounts, WABA, and other Meta assets in one place.
A **business portfolio** is the top-level container Meta uses to hold all of your business assets in one place: Facebook Pages, Instagram accounts, ad accounts, your WhatsApp Business Account, and the team members who manage them. Meta renamed this from "Business Manager" to "Business portfolio" in 2024, and the URL was renamed from `business.facebook.com` to the same domain but with new path patterns. Most pages and tutorials still use the older name.
You need a portfolio before you can do anything else in the Meta setup sequence. This page covers what a portfolio is, how to create one, and the common pitfalls.
## Do you already have one?
Many teams already do without realising. You have a portfolio if:
* You've run a Facebook or Instagram ad in the last few years
* You manage a Facebook Page that has more than one admin
* You've ever clicked through to `business.facebook.com` and seen any business assets
To check, go to [business.facebook.com](https://business.facebook.com) and sign in with the Facebook account that you'd use for work. If you see a business name at the top-left and a list of assets, you have a portfolio. Skip to [Provide official business information](/meta/business-verification#what-meta-needs).
## What a portfolio holds
Think of the portfolio as the root of an organisation chart for your Meta assets. Below it sit:
* **Pages** — Facebook Pages your business owns
* **Instagram accounts** — Instagram profiles linked to those Pages
* **Ad accounts** — the billing/budget containers for Facebook & Instagram ads
* **WhatsApp Business Accounts (WABAs)** — the WhatsApp-specific containers that hold phone numbers and templates
* **Apps** — anything you build on Meta for Developers
* **People** — the team members granted access, with their roles and permissions
* **Partners** — other portfolios (typically agencies) granted access to your assets
All of these live in the same portfolio so you can grant your team access to everything at once rather than asset by asset.
## Creating a portfolio
Go to [business.facebook.com](https://business.facebook.com) with the Facebook account that will be the primary admin of the business. Use a personal Facebook account that belongs to a long-term employee, not a shared address.
Avoid using a brand-new Facebook account for this. Meta flags brand-new accounts that immediately create business assets as suspicious, which can slow down verification later.
Click your profile picture at the top-right, then **Create a business portfolio**. If you already manage portfolios, click the portfolio switcher at the top-left, then **Create new**.
Provide:
* **Business and account name** — the trading or brand name customers know
* **Your name** — the primary admin
* **Business email address** — a real, monitored address on the business domain (`name@yourcompany.com` is much better than a Gmail)
These are administrative details, not the legal business information needed for verification. You'll add those separately later.
Meta sends a confirmation email to the address you provided. Click the link to verify it. The portfolio is created and you'll land on the Meta Business Suite home for it.
After creation, find the **business portfolio ID** (a 15- or 16-digit number) in **Business Suite → Settings → Business info**. Save it somewhere; you'll be asked for it during Flowella onboarding and any future Meta support tickets.
## Common pitfalls
The Facebook account that creates the portfolio is the original admin. If that account is later deactivated (employee leaves, account hacked, etc.) you'll have access problems. Either use an account on a long-term employee's name, or immediately add at least one other admin so the portfolio doesn't depend on a single person.
Some teams accidentally end up with two portfolios for the same business because different people set things up at different times. Meta verification is portfolio-specific, so a second portfolio means a second verification, second WABA, and split assets. Try to consolidate before getting too far.
If you need to merge two portfolios, Meta has a request form, but it's slow and not guaranteed. Better to pick one portfolio and migrate assets to it manually.
Don't put assets that genuinely belong to a different business in your portfolio. Meta verification will check that the assets and the legal business match. If the portfolio contains a Page or ad account that's clearly someone else's, verification can fail.
The portfolio name should be the **legal or trading name of the business**, not a product name. If your business is "Acme Marketing Ltd" and you sell a product called "Flowmaster", name the portfolio "Acme Marketing", not "Flowmaster". Product-named portfolios cause confusion in verification because they don't match Companies House (or equivalent).
## Adding people to the portfolio
Once the portfolio exists, grant your team access:
**Settings → Users → People → Add**.
Enter their work email. They'll get a Facebook notification to accept.
Meta has two role tiers: **Full control** (admin of the whole portfolio) and **Limited access** (specific roles like Manage business finances, Manage WhatsApp Account, Manage Pages, etc.).
For the person who'll add the WhatsApp payment method, grant **Manage business finances**. For the person who'll send WhatsApp messages via Flowella, grant **Manage WhatsApp Account** on the specific WABA.
For limited-access users, pick which Pages, ad accounts, WABAs, and other assets they can see and the role they have on each.
Grant the minimum role each person needs to do their job. Full-control admins can transfer business ownership, delete the portfolio, and remove other admins, so it's a powerful role.
## What's next
With the portfolio created and populated:
* [Business verification](/meta/business-verification) — prove to Meta that the business is real and you own it. Required to graduate WhatsApp messaging limits.
* [WhatsApp Business Account](/meta/whatsapp-business-account) — the WhatsApp-specific container inside the portfolio.
* [Setup sequence](/meta/setup-sequence) for the full picture of where this fits.
# Business information and verification on Meta
Source: https://knowledge.flowella.io/meta/business-verification
Complete your business information in your Meta portfolio and pass Business Verification, with a dummy-asset workaround for the Start Verification button.
Business Verification is Meta's process for confirming that your company is real, owned by you, and operating legitimately. It is the single most common stuck-on-setup step in Flowella onboarding because the **Start Verification** button on a fresh business portfolio is often greyed out, with no obvious reason why.
This page covers the information Meta needs, how the verification itself runs, and the workaround for the greyed-out button.
## Why verification matters
**Sending WhatsApp Flows to customers requires a verified business.** This is a Meta prerequisite, so until your business is verified you cannot send Flows, which is the core of what Flowella does. See Meta's [Flows prerequisites](https://developers.facebook.com/documentation/business-messaging/whatsapp/flows/gettingstarted).
Beyond Flows, verification also affects how widely you can message. Without passing Business Verification, your WhatsApp Business Account is capped at the Tier 1 messaging limit (250 unique recipients per 24 hours). Plain template messages can still be approved and sent within that cap, but you cannot graduate to higher tiers, and some features are disabled. Most teams hit the cap on day one of a real campaign.
For the messaging tiers themselves, see [Messaging limits for new accounts](/meta/messaging-limits).
## What Meta needs
Before starting verification, gather the following so it's all to hand once you click the button. Mismatches are the most common reason verification fails on the first attempt.
The **exact registered name** of your company as it appears on your incorporation documents and at your country's business registry (Companies House for the UK, equivalent registries elsewhere).
"Acme Marketing Ltd" and "Acme Marketing Limited" are different to Meta's matcher even if you treat them the same in daily use. Use the form that appears on your registry filings.
The **registered legal address** of the company, again as it appears on public filings. A c/o address (e.g. care of your accountants) is fine if that's what the registry shows.
Trading addresses, virtual offices, and PO boxes are accepted but slow down the manual review if Meta cannot match them to public records.
A phone number that is clearly associated with the business. Meta will call this number during verification, so it has to ring through to a person who can confirm details — not an IVR menu that drops calls to voicemail. A mobile that goes to your operations manager is often a better choice than a switchboard.
A live website on a domain you own, where the legal business name appears on the homepage, the About page, or the footer. Squarespace and Wix sites count.
If your trading brand is different to the legal entity (for example, "Flowella" trading from "Discover Digital Solutions Limited"), both names need to be visible somewhere on the website. The Privacy Policy and Terms pages are common places to expose this.
An email address on the same domain as your website (`name@yourcompany.com`). Gmail and Outlook addresses are accepted but flagged for additional review.
Be ready to upload at least one of: certificate of incorporation, business licence, tax registration document, utility bill in the business name, or recent bank statement in the business name. PDF or clear photo is fine.
All four corners of the document must be visible and all text legible. Cropped images and screenshots usually fail.
## Add or update your business information
Before starting verification you need the basics filled in on the portfolio.
Go to your Meta business portfolio in **Meta Business Suite** → **Settings** → **Business info**, or directly at `business.facebook.com/settings/info`.
Fill in the legal name, address, phone, website, email, and primary contact. Save each section as you go.
Open your website in a separate tab and verify the legal name matches what appears publicly. If they differ, update the website first.
With that done, the **Start Verification** button should appear in the Security Centre. If it doesn't, you've hit the dummy-asset trap below.
## The Start Verification button is greyed out
This catches teams with brand new business portfolios. Meta will not start the verification process for a portfolio that has no business assets attached to it — the assumption being that there is nothing to verify against. A WABA on its own does not count as a sufficient asset to trigger verification.
The fix is to attach any single Meta asset to the portfolio. The lightest-weight option is to create an **App** in [Meta for Developers](https://developers.facebook.com), which takes about 90 seconds and never has to actually be used.
Sign in at [developers.facebook.com](https://developers.facebook.com) with the same Facebook account that admins your business portfolio.
Click **My Apps** → **Create App**. Pick **Other** as the use case, **Business** as the app type, and give it any name ("Verification Helper" is fine).
When prompted for a business portfolio, choose the portfolio that holds your WABA. Save.
Back in Meta Business Suite, go to **Settings** → **Security Centre** and refresh the page. The **Start Verification** button should now be active.
Walk through Meta's verification flow with the information you gathered above.
Once verification succeeds you can leave the dummy App attached or delete it from `developers.facebook.com` → the App → **Settings** → **Delete App**. Either is fine.
## During verification
Meta typically responds within 1–2 business days. The flow is:
1. **Automatic checks first.** Meta compares your legal name, address, and website against public records and the documents you uploaded. If everything matches, you're verified in minutes.
2. **Manual review if mismatched.** Anything Meta can't auto-match goes to a human reviewer, which adds 1–2 business days. You may be asked to upload additional documents or take a verification call.
3. **Phone or email confirmation.** Meta sends a verification code to either your business phone or business email — you choose which. Enter the code to finish.
You can check status anytime under **Security Centre** → **Business Verification**.
## Common rejection reasons
Even small differences fail: punctuation, missing "Limited" vs "Ltd", capitalisation variations. Pull the exact string from Companies House (UK) or your country's equivalent and use it verbatim.
Meta requires the legal name to be visible on your live website. If your brand differs from the legal entity, add the legal name to your footer, Privacy Policy, or Terms page.
Cropped, blurry, or screenshot-quality uploads fail. Use a flatbed scanner or take a phone photo in good light with all four corners visible.
Meta may search your business phone number against public records. If it doesn't match (for example, a personal mobile), the review takes longer. List the number on your website's contact page to make the link clear.
Brand new portfolios sometimes face additional manual review even after the Start Verification button works. Adding the dummy App helps Meta accept that the portfolio is real.
## After verification
Verification unlocks:
* **Sending WhatsApp Flows to customers.** Flows cannot be sent until your business is verified, which is the main reason most Flowella customers complete this step. See Meta's [Flows prerequisites](https://developers.facebook.com/documentation/business-messaging/whatsapp/flows/gettingstarted).
* **Higher messaging limits** — graduating from Tier 1 (250 recipients/24h) up to Tier 4 (100,000+/24h) becomes possible. See [Messaging limits](/meta/messaging-limits) for the criteria.
* **Display name approval** — the green badge in WhatsApp comes from a verified business with an approved display name.
* **Click-to-WhatsApp ads** — unverified accounts can't run CTWA at scale. See [CTWA Ads](/campaigns/click-to-whatsapp-ads).
If verification has succeeded but Flowella still shows a warning, open Flowella → **Settings** → **Meta** and click **Refresh status**. The Meta status syncs to Flowella on a schedule but a manual refresh forces an immediate read.
## Related guides
* [Setup sequence](/meta/setup-sequence) for where verification sits in the bigger picture
* [Phone numbers explained](/meta/phone-numbers) for the parallel step of getting a working number registered
* [Meta payment method](/meta/payment-method) once verification is complete
# WhatsApp Co-existence: Use Your Business App with Flowella
Source: https://knowledge.flowella.io/meta/co-existence
Connect your existing WhatsApp Business App number to Flowella so you can keep using the app for 1:1 chats while Flowella handles automation at scale.
Co-existence lets you connect your existing WhatsApp Business App number to Flowella without giving up your current number or replacing it. Once enabled, you can continue sending and receiving 1:1 messages in the WhatsApp Business App while Flowella powers automation at scale, including Flows, forms, HubSpot submissions, templates, and workflow triggers.
## What is co-existence?
When you enable co-existence, your WhatsApp Business App account and number are connected to the **WhatsApp Business Platform (Cloud API)**. From that point:
* You can continue sending and receiving 1:1 messages in the WhatsApp Business App.
* Flowella can also send and receive messages via the Cloud API.
* 1:1 message history stays in sync between the WhatsApp Business App and Flowella, subject to the sharing choice you make during setup.
## When to use co-existence
Use co-existence if you:
* Already have a WhatsApp Business App number that customers know and trust
* Want to add automation without changing your number
* Still want staff to use the WhatsApp Business App for quick, human replies
Do **not** use co-existence if your number is already connected to a WhatsApp API provider (for example, Superchat, Twilio, or any other BSP tool). A phone number can only be connected to one API provider at a time. In that case, you will need to either use a new number for Flowella, or migrate the existing number to Flowella by disconnecting it from the current provider first.
## Requirements and eligibility
To connect an existing WhatsApp Business App number, Meta requires:
* **WhatsApp Business App version 2.24.17 or higher**
* Your phone number's country code must be supported. **Nigeria and South Africa are not currently supported**.
* Access to the WhatsApp Business App on the device that owns the number
* The right permissions in your Meta Business settings to complete the Embedded Signup flow
## What changes after enabling co-existence?
Co-existence is designed to keep the WhatsApp Business App fully usable, but some features change to stay compatible with the Business Platform:
| Feature | After co-existence |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Message throughput | Fixed at **20 messages per second (mps)** |
| Chat history sync | Up to **6 months** of 1:1 history (optional) |
| Group chats | Unchanged in the app; not available in Flowella |
| Disappearing messages | Turned off for all 1:1 chats |
| View once messages | Disabled for all 1:1 chats |
| Live location | Disabled for all 1:1 chats |
| Broadcast lists | Disabled; existing lists become read-only |
| Voice/video calls | Still work in the app; not supported by Cloud API |
| Linked devices | Companion clients are unlinked after onboarding; some can be re-linked (WhatsApp for Windows and WearOS are not supported) |
If messages stop appearing in Flowella, check whether staff are using unsupported companion devices such as WhatsApp for Windows. Messages sent from those devices may not trigger API webhooks.
## Setup: Connect your WhatsApp Business App number to Flowella
In Flowella, begin connecting WhatsApp. This launches Meta Embedded Signup. When you see the setup choice screen, select **Connect your existing WhatsApp Business App**.
Meta will ask you to verify that you own the WhatsApp Business App number. Flowella displays a **verification code** and the steps to follow. Keep this screen open.
On your phone, open the WhatsApp Business App and look for a message from the official **Facebook Business** account. Tap **Connect**.
If you do not see the message, go to **Settings → Account → Business Platform** and select **Connect to the Business Platform**.
You will be prompted to decide whether to share existing chat history with Flowella.
* **Share chats:** Flowella can sync up to 6 months of 1:1 messages.
* **Don't share chats:** Flowella starts from new conversations only.
This choice cannot be changed later without fully disconnecting and redoing the onboarding process. Take a moment to decide before proceeding.
Enter the verification code shown in Flowella into the WhatsApp Business App (or scan the QR code if that option is offered).
Tap **Connect to the Business Platform** when prompted in the WhatsApp Business App.
Return to your browser and finish Meta's Embedded Signup steps. Once complete, Flowella finalises the setup.
After onboarding, Flowella synchronises contacts and, if you chose to share, chat history. Keep the **WhatsApp Business App open** during synchronisation. This can take several minutes depending on the size of your chat history and your connection speed.
Meta requires synchronisation to begin within **24 hours** of completing onboarding. Flowella initiates this automatically, so it is best to complete all steps in one sitting without closing the app.
## What gets synchronised?
| Data | Synchronised? |
| -------------------------------- | ----------------------------------------------------------------------------- |
| Contacts | Yes. WhatsApp contacts can be synced to appear in Flowella |
| 1:1 chat history (last 6 months) | Yes, if you chose "Share chats" during setup |
| Group chats | No. Group chats remain in the WhatsApp Business App only |
| Media in older messages | Partial. Meta may send media asset details separately and not for older media |
## Pricing and messaging rules
* Messages sent via the **WhatsApp Business App** remain free, as per Meta's standard rules.
* Messages sent via **Flowella (Cloud API)** are subject to **Cloud API pricing**.
A customer service window is opened when a WhatsApp user messages your business after you are onboarded to Cloud API. If a user messaged you just before onboarding, you may only be able to reply with a **template** message until a new customer service window opens.
## Disconnecting (offboarding)
If you want to stop using Flowella with a co-existence number:
1. Open the **WhatsApp Business App**.
2. Go to **Settings → Account → Business Platform → Disconnect Account**.
Once disconnected, Flowella can no longer send or receive messages for that number.
## Troubleshooting
**I did not receive the message from Facebook Business**
* Ensure WhatsApp Business App is updated to version 2.24.17 or higher.
* Go to **Settings → Account → Business Platform** and try connecting from there directly.
* Check your internet connection and that notifications are enabled.
**The verification code does not work**
* Restart the connection from Flowella to generate a new code.
* Avoid copying extra spaces when pasting the code.
* Try the QR code option if it is available.
**I get an error when switching from another provider**
If you previously used another partner and still share a credit line with them, Meta may block switching until that is resolved. Contact Flowella support and share the error details.
**Some messages do not appear in Flowella**
This can happen when staff use unsupported companion devices such as WhatsApp for Windows. Ask them to reply from the primary device or a supported companion app.
## FAQs
Yes. That is the purpose of co-existence. Your team can continue using the WhatsApp Business App for 1:1 chats while Flowella handles automation.
No. You can choose "Don't share chats" during setup. In that case, Flowella will only have access to new messages received after onboarding.
No. Group chats remain in the WhatsApp Business App only and are not synchronised to Flowella.
Not on the same phone number at the same time. You will need to either use a new number for Flowella, or migrate the number away from your current provider before connecting it to Flowella.
## Related
How a number becomes a WhatsApp Business Platform sender.
The WABA your number lives in and the rules around moving it.
The right order for connecting Meta when co-existence is in play.
Run more than one WhatsApp sender from a single Flowella org.
# WhatsApp messaging limits and how to graduate tiers
Source: https://knowledge.flowella.io/meta/messaging-limits
How Meta's Tier 1–4 messaging limits work for WhatsApp Business Platform, what triggers a tier upgrade, and how to avoid hitting the daily cap.
Meta caps how many unique recipients each WhatsApp phone number can message in a rolling 24-hour window. The cap depends on the **messaging tier** assigned to that number, ranging from 250 unique recipients per day at Tier 1 up to unlimited at Tier 4. This page explains how the tiers work, what triggers a tier change, and how to avoid being capped mid-campaign.
## The four tiers
| Tier | Unique recipients per 24h | When you get it |
| ------------- | ------------------------- | ----------------------------------------------- |
| **Tier 1** | 250 | Default for every new phone number |
| **Tier 2** | 1,000 | Automatic graduation when criteria are met |
| **Tier 3** | 10,000 | Automatic graduation when criteria are met |
| **Tier 4** | 100,000 | Automatic graduation when criteria are met |
| **Unlimited** | Unlimited | Available to verified accounts in good standing |
"Unique recipients per 24 hours" means: if you message 250 different contacts in a day at Tier 1, you cannot message a 251st until 24 hours after the first message. Messaging the same contact twice in the window does not count as two recipients, just one.
## What counts toward the limit
Only **business-initiated** template messages count. Replies inside the **24-hour customer service window** (where the customer has messaged you first) do not count toward the tier limit — those are essentially unlimited.
This matters for campaign planning: a typical outbound nurture pulse counts, but the follow-up Q\&A conversation that happens after a customer replies does not.
## How to graduate to the next tier
Meta evaluates each phone number daily. To graduate from your current tier to the next, the number must:
1. **Have sent template messages to at least 1,000 unique users in the last 7 days** if you're on Tier 1, or higher counts for higher tiers
2. **Hold a Green or Yellow [quality rating](/meta/quality-score)** — a Red rating blocks tier upgrades and can trigger a downgrade
3. **Not be flagged for policy violations** in the same period
Meta usually upgrades automatically within 24 hours of meeting all three. There is no manual request to graduate; the system handles it.
## Why graduation is sometimes slow
New accounts often graduate Tier 1 → Tier 2 within days of starting consistent outreach, then stall before Tier 3 because:
* **Block rate is too high.** Even at Tier 2, sending 1,000 messages a day to a list with even 1% block rate causes Meta to pause graduation. See [quality score](/meta/quality-score).
* **Volume isn't consistent.** Sending 1,000 messages in one day and zero for six days won't graduate you the way 200 per day for seven days will.
* **Recipient mix is too narrow.** Repeatedly messaging the same small audience doesn't show Meta you can reach unique users at higher volumes.
## How to avoid hitting the limit mid-campaign
Before you launch, check **Settings → Meta** in Flowella for your current tier. If your list is bigger than the tier allows, either:
* **Spread the campaign over multiple days.** A 5,000-recipient campaign on Tier 2 needs at least 5 days at 1,000 per day.
* **Use a higher-tier number.** If you have multiple phone numbers, send from the one with the highest tier.
* **Trim the list to fit the tier.** Better to land cleanly with 1,000 well-targeted recipients than queue 5,000 and have 4,000 sit waiting.
A brand-new phone number starts at Tier 1 with no quality history. Don't immediately blast 250 messages on day one to a cold list — if the response is poor, you'll get a Yellow rating and graduation stalls.
Start small: 50–100 messages a day to engaged contacts (people who've opted in recently and know your brand), then increase as you build quality history.
Tier downgrades happen when quality drops or block rates spike. Meta usually flashes a warning in WhatsApp Manager a few days before downgrading, but you can also watch Flowella's Analytics page for spikes in block rate or template rejection.
Each phone number has its own tier limit. Two Tier 2 numbers give you 2,000 unique recipients per 24 hours total, which is often easier than waiting to get a single number to Tier 3.
## Reading your current tier in Flowella
Flowella surfaces the current tier and approximate remaining capacity on **Settings → Meta** (under the phone number details) and on the **Dashboard → Channels** widget. The number you see is the cap; what you're using is shown as a percentage.
If the percentage is climbing fast during a campaign, throttle the send rate or split it across multiple numbers. Flowella does not automatically pause sends to stay under the cap — you'll see errors from Meta once you've hit it, and the remaining messages get queued for the next 24-hour window.
## Service window messages and the 24-hour rule
A reminder about the **customer service window**: any free-form (non-template) message must be sent within 24 hours of the customer's last message to you. Outside that window, you can only send template messages, which are what the tier limits apply to.
This means Flowella's two-way conversation features (Inbox replies, AI agent handoffs, Form fills) are essentially unlimited as long as the customer initiated the conversation. The tier limit only constrains outbound nurture, broadcasts, and re-engagement campaigns.
## Related guides
* [Quality score](/meta/quality-score) — the Green/Yellow/Red rating that gates tier upgrades
* [Business verification](/meta/business-verification) — Tier 4 and unlimited messaging require a verified business
* [Campaigns overview](/campaigns/overview) — how to plan outbound work around your tier
# Add a credit card to your WhatsApp Business Account on Meta
Source: https://knowledge.flowella.io/meta/payment-method
Add a credit card to your WhatsApp Business account in Meta Business Suite and set it as the default payment method so WhatsApp delivery is never paused.
Meta charges your business directly for WhatsApp messages sent through the WhatsApp Business Platform. Those charges land on a credit card attached to your WhatsApp Business Account (WABA), not on your Flowella subscription. If the card is missing, declined, or sitting alongside a different card that is set as the Default, Meta will limit or block outbound business-initiated messages once you exhaust the free service tier.
This guide walks you through adding a credit card to your WABA in **Meta Business Suite**, then confirming the card is set as the **Default** payment method. Run through it once during onboarding, and again any time you change cards.
Flowella does not charge, store, or mark up this card. It sits with Meta and Meta invoices you against it directly. For your Flowella subscription card, see [Billing](/account/billing).
## Before you start
Make sure you have:
* **Full control of the business portfolio**, or the **Manage business finances** role on it. If you have a more limited role, you will not see Payment Settings on the WABA.
* **Manage WhatsApp Account** permission on the specific WABA you want to bill against. Ask the portfolio admin to grant this if the WABA does not appear in your list.
* A **Visa, Mastercard, or American Express** (region permitting) that is enabled for international and online transactions. Direct debit and most prepaid cards are not accepted.
* The card's **billing address** to hand, in the exact format your bank holds it.
Use a card with a generous limit and predictable settlement currency. Meta bills in the currency tied to your WABA, which cannot be changed after a payment method is attached, so pick the right currency the first time.
## Add the credit card
Sign in at [business.facebook.com](https://business.facebook.com) with the Facebook account that has admin access to your business portfolio. If you manage more than one portfolio, use the dropdown at the top left to switch to the portfolio that owns your WABA.
![Meta Business Suite home, portfolio switcher highlighted]()
Click the **gear icon** (Settings) in the left-hand navigation. Under **Accounts**, select **WhatsApp accounts**. You will see every WABA in this portfolio.
![Settings, Accounts, WhatsApp accounts panel in Meta Business Suite]()
Click the WABA you connected to Flowella. The details panel opens on the right. If you have multiple WABAs, pick the one whose phone numbers you actually send messages from.
In the WABA details view, click **Payment settings**. This jumps you to the billing screen for that specific WABA, separate from any advertising payment methods.
![Payment settings link inside a WABA details panel]()
Click **Add payment method**. In the dialog, set your **business country** and **currency**, then choose **Credit or debit card** as the payment type.
Country and currency are tied to the WABA and **cannot be edited once a payment method is attached**. Double-check both before you continue.
![Add payment method dialog in Meta Business Suite]()
Fill in:
* Name on card (exactly as printed)
* 16-digit card number
* Expiry date (MM/YY)
* CVV / CVC
* Billing address (must match your bank's records)
Click **Save**. Meta runs a small authorisation charge against the card to verify it, which is automatically reversed.
![Credit card details form in Meta Business Suite]()
If your bank challenges the authorisation (3-D Secure, one-time passcode, or an in-app approval), complete the step on your phone or banking app. The Payment settings screen refreshes when verification succeeds.
The card is now attached to your WABA. The next section is the bit most people miss.
## Confirm the card is set as Default
Meta lets you attach multiple cards to a business portfolio. At the WABA (WhatsApp Business account) level, exactly one card carries the **Default** badge:
* **Default**: Meta charges this card for every WhatsApp invoice on this WABA.
* **No label**: other cards attached to your business portfolio that are not the Default. Meta does not charge these for WhatsApp; they only become active if you explicitly promote them.
If this is the first card you have ever attached to the WABA, Meta sets it as Default automatically. But if your portfolio already had a card on file (for ads, for example) and the new card has been added without the Default badge, **WhatsApp charges will continue to bill the existing Default**. That is exactly the trap behind "I added a card but my account still shows a payment warning."
Always verify the badge after you add the card.
From the same WABA Payment settings screen, scroll to **Payment methods**. Every card attached to this WABA is listed.
Look for a **Default** badge next to the card you just added.
* If it shows **Default**: you are done. Skip to [Verify the setup](#verify-the-setup).
* If it shows no badge: continue to the next step.
![Payment methods list showing the Default badge]()
Click the **three-dot menu** (⋯) next to the new card and choose **Make default**. Confirm when prompted. The badge moves to the new card and the previous Default drops to an unlabeled state.
![Make default option in the card three-dot menu]()
If the old card was a placeholder you no longer want, click its three-dot menu and choose **Remove**. Otherwise, leave it attached to the portfolio so Meta has something to fall back on if you ever need to swap it back in.
A card without the **Default** badge does **not** keep your WhatsApp Business Platform account in good standing on its own. Meta only charges the Default card on each WABA. If no card holds the Default badge, message limits and template approvals can be paused.
## Verify the setup
Before you close the tab, run through this quick checklist:
1. The Payment settings screen for the WABA shows **at least one card**, with the **Default** badge on your preferred card.
2. The WABA's **country and currency** match how you want to be invoiced.
3. No red banners or **Payment method needed** warnings appear on the WABA, in WhatsApp Manager, or in your Flowella dashboard.
Open Flowella's [Dashboard](/app/dashboard) and confirm the **Channels** section shows the WABA as healthy. If a payment-related warning was previously shown there, it should clear within a few minutes once Meta records the Default card.
## Updating or replacing the card later
Cards expire and sometimes get reissued. To swap the card without dropping billing:
1. Add the new card first using the steps above so it sits alongside the existing one.
2. **Promote the new card to Default** before removing the old one.
3. Only then remove the old card from **Payment settings → Payment methods**.
This order matters. If you remove the old card before promoting the new one, Meta can briefly leave the WABA with no Default card, which is what triggers the missing-payment-method warnings.
## Troubleshooting
Payment settings only appears for users with full control of the business portfolio or the **Manage business finances** role. Ask your portfolio admin to assign you that role on the portfolio that owns the WABA, then refresh the page.
Most decline reasons fall into one of three buckets:
* **International or online transactions are blocked** on the card. Turn these on in your banking app and retry.
* **Billing address mismatch.** The address must match what your bank holds on file, character for character.
* **3-D Secure not completed.** Check your banking app for an approval prompt and try again.
If it still stalls, try a different browser or a private window to rule out an extension blocking the authorisation step.
The most common cause is that the new card has been added to the portfolio but **does not carry the Default badge** on the WABA. Reopen **Payment settings → Payment methods** and confirm the **Default** badge is on the right card. If it isn't, follow the steps in [Confirm the card is set as Default](#confirm-the-card-is-set-as-default).
Other causes: the card was attached at the **business portfolio** level for ads rather than at the **WABA** level for WhatsApp, or the WABA shown in Meta is a different one to the WABA connected to Flowella. Open Flowella **Settings → Meta** and check the WABA name matches the one you just edited.
Country and currency are locked once a payment method is attached. If they are wrong, you usually need a new WABA in the correct country. Contact Flowella support before creating one so we can move your phone number across cleanly.
Credit lines are available to larger advertisers via Meta's monthly invoicing programme and need a separate application through your Meta representative. WhatsApp Business Platform charges can then be billed against the shared line of credit. For most Flowella customers a credit card is faster and simpler, especially at the start.
## What this card pays for
This payment method covers **Meta's WhatsApp Business Platform fees**: per-conversation or per-message charges set by Meta, varying by country and message category (marketing, utility, authentication, service). These are completely separate from your Flowella subscription, which is billed by Discover Digital via Stripe.
For a full breakdown of how Flowella subscription costs and Meta network fees sit alongside each other, see [Plans and limits](/account/plans-and-limits). For Flowella's own subscription card, see [Billing](/account/billing).
If you also run **Click-to-WhatsApp ads** from Facebook or Instagram, the ad spend is billed through your **ad account** payment method, not the WABA card you set up here. See [CTWA Ads](/campaigns/click-to-whatsapp-ads) for the full ad funnel setup.
# Phone numbers for WhatsApp Business: what works, what fails
Source: https://knowledge.flowella.io/meta/phone-numbers
Pick the right phone number for your WhatsApp Business Account: mobile vs landline, Meta-provided numbers, calls, verification, and IVR-routed numbers.
Every WhatsApp Business Account (WABA) needs at least one phone number. The choice matters more than most teams realise: the number is what customers see, what Meta verifies against, and what determines whether you can keep using the WhatsApp Business app alongside Flowella. This page is the reference for every "can I use this number?" question.
For the technical formatting (E.164) used inside HubSpot, see [Phone Numbers](/hubspot/phone-number-format) in the HubSpot Integration section.
## The eligibility rules
A phone number can be used with the WhatsApp Business Platform if it:
* Is **active and can receive an SMS or voice call** for verification
* Is **not currently registered** with the consumer WhatsApp app or the WhatsApp Business app on any device (unless you're setting up [Co-existence](/meta/co-existence))
* Is **owned by you or your business** and that ownership can be evidenced if Meta asks
* Is a **standard mobile or landline** number, not a special-purpose number
That last rule rules out a few common options. Here's the full breakdown.
| Number type | Eligible? | Notes |
| ------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| **Mobile number** | Yes | The most common choice. Personal mobiles are fine; ideally use one dedicated to the business |
| **Landline / fixed line** | Yes | Verify via voice call rather than SMS |
| **VOIP number** (Twilio, RingCentral, etc.) | Sometimes | Works if it can receive SMS or voice. Some VOIP carriers strip the verification SMS, in which case fall back to voice |
| **Meta-provided number** | No | Meta does not currently issue phone numbers. You bring your own |
| **Toll-free / freephone** (0800, 1-800) | No | Meta explicitly excludes these |
| **Shortcode** (5-digit SMS codes) | No | Not a real phone number from WhatsApp's perspective |
| **Number behind an IVR menu** | Possible | Only if you can route the verification call to a human pickup. See below |
| **Number already on WhatsApp app** | Conditional | Either fully migrate it to the platform or use [Co-existence](/meta/co-existence) |
## Can people call this number?
This is the question most teams forget to ask before they pick a number. The answer depends on what the number was *before* Meta got hold of it.
* **Mobile number that originated outside WhatsApp**: Yes, the SIM still receives calls and SMS normally. Putting it on the WhatsApp Business Platform does not stop the underlying network from delivering voice calls to the device that holds the SIM.
* **Landline number that originated outside WhatsApp**: Yes, calls still ring through to the line as normal. Some businesses register a landline with the platform specifically to keep the phone working.
* **Number on the WhatsApp Business app (consumer)**: When you migrate the number to the platform, voice calls to the WhatsApp app (the WhatsApp Calling feature) stop, but the underlying SIM still receives calls if it's a mobile.
* **WhatsApp Calling on the platform**: Meta's WhatsApp Business Calling feature is a separate product; it allows you to receive **inbound WhatsApp calls** programmatically, but is not enabled by default. Most Flowella customers do not use this.
Pick a number where receiving phone calls is acceptable in your workflow. A mobile that goes to your operations manager works well. A senior director's mobile usually doesn't, because the customer who calls back expects a customer service person.
## Verification: SMS vs voice
Meta sends a 6-digit code to the number during setup. You choose how to receive it:
* **SMS**: works on any number that can receive text messages. Most mobile networks deliver in seconds. VOIP carriers sometimes block the SMS as suspected spam.
* **Voice call**: a robotic voice reads the code twice. Use this for landlines or when SMS doesn't arrive.
Voice verification is also the fallback when SMS verification fails three times in a row — Meta automatically offers the voice option after the third failed SMS attempt.
### What if the number is behind an automated menu?
Main business numbers often hit an IVR ("Press 1 for sales, 2 for support"). Meta's voice verification call cannot navigate an IVR — the robotic voice just reads the code and hangs up.
Two workable options:
1. **Use a different number for verification, then port to the main number.** Verify a clean mobile or direct line first, then ask your telephony provider to port the IVR number to it. This is more effort but lets you keep your customer-facing main number.
2. **Temporarily disable the IVR for verification.** Ask your telephony admin to route the number to a direct extension for a 10-minute window, run the verification, then restore the IVR. This is the path of least resistance.
If neither is workable, you'll need a different number for the WABA.
## How to validate a number is eligible before you start
Run this checklist before committing a number to verification:
Some networks block international SMS by default. Send yourself a test SMS from a number in a different country, or have a colleague abroad call the number, to confirm it goes through.
On a phone where the number is *not* saved as a contact, open WhatsApp and tap **New chat**. Type the full international number. If WhatsApp finds the contact, the number is already registered.
If it is registered, you either need to delete the existing WhatsApp account on that device first, or use [Co-existence](/meta/co-existence) to keep the consumer app running.
Call the number from a phone that isn't saved as a contact. If you hit an automated menu instead of a person, plan one of the IVR workarounds above before starting verification.
For business numbers, Meta may ask for proof. A recent phone bill in the company name, or a screenshot of the number listed on your website, is usually enough.
## Once verified, can the number be moved?
Yes, with the right process.
* **From one WABA to another inside the same business portfolio**: straightforward, done in WhatsApp Manager.
* **From one BSP (business solution provider) to another**: requires the source BSP to release the number. Most major BSPs, including Flowella's WhatsApp connection, support this.
* **From the platform back to the consumer WhatsApp app**: requires deleting the number from the WABA first, after which the underlying SIM can be re-registered with the app.
If you're switching to Flowella from another tool and want to keep your existing number, you don't need to delete or re-verify — the move is a paperwork step rather than a re-setup. Contact Flowella support before you start.
## Multiple numbers per WABA
A single WABA can hold multiple phone numbers (up to 25 in most cases). This is useful when:
* You want a different number per market (UK, Spain, etc.)
* You want to separate customer service from marketing comms
* You want to test new number setups without affecting your main channel
Each number has its own display name, business profile, and message templates. They share the same billing, business verification, and team access. See [Multi-channel](/essentials/multi-channel) for how Flowella switches between them.
## Related guides
* [Co-existence](/meta/co-existence) for keeping a number on the WhatsApp Business app alongside the platform
* [Setup sequence](/meta/setup-sequence) for where number registration sits in the overall flow
* [Phone number formatting](/hubspot/phone-number-format) for the E.164 format used inside HubSpot
# WhatsApp Display Name, Profile Image & Business Info
Source: https://knowledge.flowella.io/meta/profile-setup
Learn how to configure your WhatsApp Business profile in Meta's WhatsApp Manager, what Meta approves, and how Flowella uses these settings.
Your WhatsApp Business profile is what customers see when they tap your name in WhatsApp. It includes your display name, profile image, and business information such as your description, website, email, and address. Flowella reads this data directly from your WhatsApp Business Account, so you manage and update it in Meta's WhatsApp Manager.
## Where to manage these settings
You configure your display name, profile image, and business info in **WhatsApp Manager**, which is part of Meta Business Manager.
Go to Meta Business Manager for the business that owns your WhatsApp Business Account.
Select **WhatsApp Manager** from the left navigation.
Go to **Account tools** → **Phone numbers** or **Profile**.
Select the phone number you want to update, then edit the **Profile** and **Display name** fields.
Flowella reads your display name, profile image, and business info from your WhatsApp Business Account automatically. You cannot change these fields from within Flowella; all edits must be made in WhatsApp Manager. Once updated and approved there, Flowella reflects the changes for new conversations and flows.
## Display name
Your **display name** is the business name customers see in WhatsApp instead of your phone number. It is tied to the certificate for your WhatsApp Business Platform account and must comply with Meta's guidelines.
### Approval process
Every phone number in your WhatsApp Business Account has a display name. When you add a new number or change an existing display name, Meta runs an automatic **Display Name Review**.
* Review usually completes in **1 to 3 business days**, though it is often faster.
* The status changes from "Pending" or "Review not started" to "Approved" or "Rejected" in WhatsApp Manager.
* Once approved, and once your account is verified and in good standing, the display name appears in chats instead of your phone number.
Flowella cannot speed up this review or override Meta's decision. If a name is rejected, you must update it in WhatsApp Manager and resubmit.
### Name guidelines
Your display name must:
* **Match your business or brand.** It should clearly represent your company, product, service, or a recognised brand you own, and it must be referenced on your website or official materials.
* **Comply with WhatsApp Commerce and Business policies.** For example, "ABC Wine Glasses" is acceptable; "ABC Wine" (where selling alcohol would violate policy) is not.
* **Be specific, not generic.** Single generic words such as "Fashion", "Shoes", or "Support" are not permitted, nor are generic location names such as "London" or "New York" on their own.
* **Show a clear business relationship.** If the brand differs from the legal entity, the link must be publicly visible (for example, "Fruit Snacks by Fresh Produce", where both names appear on your websites).
* **Follow basic formatting rules:**
* At least **3 characters** long
* Normal capitalisation that matches your branding
* No emojis, extra punctuation, or random symbols
* Must not look like a URL or use a domain format such as `Example.com`
Common reasons Meta rejects a display name:
* Using **"WhatsApp", "Facebook", "Meta", "Official", "Verified"**, or similar terms in your name
* Using a slogan, long sentence, or tagline instead of a business name
* Using a person's full name instead of a business or brand name
* The name has no clear relation to your website, legal entity, or public branding
If your display name is rejected, update it to meet Meta's rules and resubmit from WhatsApp Manager. Flowella support can review screenshots and links to help you identify issues before you resubmit.
## Profile image
Your **profile image** is the small icon that appears next to your name and on your WhatsApp Business profile. For API accounts, it is typically your logo or a simple brand mark.
### Technical guidelines
* **Square image**, typically **640 × 640 px** or higher resolution
* **JPG or PNG** format
* File size up to **5 MB**
* The key part of your logo should be centred and visible inside a small circle
### Content guidelines
To avoid problems, your profile image should:
* Represent your business or brand clearly
* Avoid misleading content, adult content, hate symbols, or anything that violates WhatsApp's Commerce or Business policies
* Be high quality and readable on a mobile screen
If you update the profile picture in WhatsApp Manager, it can take a few minutes for changes to appear in WhatsApp and then in Flowella.
## Business information
Your WhatsApp Business profile supports several additional fields:
* Business description
* Address
* Website URL(s)
* Email address
* Business category or vertical
* Opening hours
You can edit these fields in WhatsApp Manager under the profile or business info section for your number. A complete profile helps customers trust that the number genuinely belongs to your organisation and gives them alternative ways to reach you outside WhatsApp.
## Best practice checklist
Before going live with Flowella, work through the following:
1. Choose a display name that matches your website and public brand. Avoid generic terms and any wording that violates Meta's policies.
2. Use a clean, square logo that looks clear inside a circle and meets brand and content requirements.
3. Complete your business profile. Add a description, website, and contact details in WhatsApp Manager.
4. Allow up to a few business days for display name approval before launching major campaigns.
If your display name or profile image is repeatedly rejected and you are unsure why, check that the name and brand appear clearly on your website, remove any restricted or generic terms, and contact Flowella support with screenshots and links before resubmitting.
## Related
Verify your Meta Business Account before display names can go live.
Add and verify the number that runs your WhatsApp Business Account.
What Meta watches after launch and how display name interacts with it.
The full order of Meta setup steps and where profile setup fits in.
# Phone number quality rating: Green, Yellow, Red
Source: https://knowledge.flowella.io/meta/quality-score
How Meta calculates the quality rating on each WhatsApp phone number, what triggers Yellow and Red statuses, and how to recover before sending is paused.
Every WhatsApp phone number on the Business Platform carries a **quality rating** that Meta uses to decide whether the number can keep sending and whether it deserves to graduate to higher [messaging tiers](/meta/messaging-limits). The rating is a traffic light:
* **Green** — high quality. No restrictions. Tier upgrades can happen.
* **Yellow** — medium quality. No immediate restrictions, but tier upgrades are paused. A warning to fix things before they slip to red.
* **Red** — low quality. Messaging is heavily restricted, and Meta can pause your account entirely if the rating doesn't recover.
This page covers what drives the rating, how to read it in Flowella, and how to recover if you slip.
## What Meta tracks
The quality rating is mostly driven by **recipient signals** — how the people you message react. The big inputs:
* **Block rate.** What proportion of recipients block your number? This is the single largest factor. Even small numbers (1–2%) move ratings down quickly.
* **Report rate.** What proportion explicitly reported your messages as spam in WhatsApp? Less common but heavily weighted when it does happen.
* **Read rate.** Are your messages getting opened or sitting unread for days? Persistent unread implies the recipient isn't interested.
* **Reply rate.** Do recipients engage back, or is your sending one-way?
* **Recency.** Recent signals matter more than historical ones. A bad week tanks the rating quickly; a good week recovers it within a few days.
* **Volume.** A number sending 50 messages a day is judged more leniently than one sending 5,000. Higher-volume numbers face stricter quality standards.
Meta doesn't publish exact thresholds, but block rate above \~2% reliably triggers Yellow, and above \~4–5% triggers Red.
## Why ratings move down
Most rating slips come from one of three patterns:
The single biggest cause. "They gave us their phone number when they bought from us five years ago, so we can message them on WhatsApp" is not consent. Customers don't expect a marketing message via WhatsApp and they block more aggressively than they would on email.
Fix: only send to contacts who've **explicitly opted in to WhatsApp** in the last 6–12 months. Run a re-permission campaign by SMS or email if you need to refresh consent.
WhatsApp is a more personal channel than email. Once a week to the same person is high frequency; daily is almost always too much. Block rates spike when you exceed what the audience can tolerate.
Fix: cap per-recipient frequency in your workflow design. A simple rule: "no more than one outbound template per recipient per 7 days unless they replied to the last one."
A customer who signed up for booking reminders doesn't expect a marketing template. A customer who signed up for marketing doesn't expect a transactional verification message they didn't ask for. Either way, the mismatch causes blocks.
Fix: align template categories to the consent the recipient gave you. See [Template rejected](/troubleshooting/template-rejected) for category guidance.
If your display name is "Acme Marketing Ltd" but the customer signed up with the brand "Flowmaster", they may not recognise the sender and block as spam. Pick a display name that customers will recognise.
## Reading the rating in Flowella
Flowella surfaces the current quality rating on:
* **Settings → Meta** — listed next to each phone number, refreshed every few minutes from Meta
* **Dashboard → Channels** widget — quick traffic-light summary
* **Analytics** — longer-term trends including block-rate spikes
If a rating moves down, Flowella shows a warning banner with a link back to this page.
## How to recover from Yellow
Most Yellow ratings recover within 3–7 days **if** you immediately change what you're doing. Don't just keep sending and hope.
Pause any active outbound templates. Send nothing for at least 24 hours.
Look at recent block-rate spikes in Analytics. Which campaign correlates? Which template category? Were any of them sent to a list that wasn't recently opted in?
For the next sends, restrict to your most-engaged audience: contacts who've replied recently, or who you know opted in within the last 90 days.
Send half the volume you were sending before, for a week. Lower volume gives Meta less recent data to weight, and it gives your block rate room to recover proportionally.
Check daily. Within a week of clean sends, Yellow usually returns to Green.
## How to recover from Red
Red is more serious. Meta restricts the number's messaging while Red, and prolonged Red can cause the number to be **flagged** or **paused** entirely.
Same steps as Yellow, but:
* **Stop sending immediately, not just pause campaigns.** Including transactional templates if they're causing blocks.
* **Take longer to ramp back up.** Two weeks of light, well-targeted sending before resuming normal volume.
* **Consider a new display name** if customers consistently don't recognise the sender.
* **Open a Meta support ticket** if the rating doesn't move after a fortnight of clean behaviour. Sometimes a recent flag can be appealed.
If the number is paused outright, your only option is to wait for Meta to lift the pause (usually 2–4 weeks) or move to a different number.
## Preventing rating drops in the first place
The boring advice is the most effective:
* **Build the opt-in flow with WhatsApp in mind.** Make the channel explicit at signup, not assumed.
* **Set frequency caps in HubSpot workflows.** Never let two campaigns fire to the same recipient on the same day.
* **Send the right template to the right person.** Use HubSpot lists and properties to segment, not blast.
* **Watch the early signals.** Block-rate spikes appear in Analytics within hours; respond to them quickly, not after a week.
## Related guides
* [Messaging limits](/meta/messaging-limits) — the tier system that quality rating gates
* [Template rejected](/troubleshooting/template-rejected) — fixing the templates that drive ratings down
* [Managing opt-outs](/app/opt-outs) — keeping consent clean to avoid blocks
# Setting up Meta for WhatsApp Business: end-to-end sequence
Source: https://knowledge.flowella.io/meta/setup-sequence
The eight steps required to go from no Meta presence to a WhatsApp Business Account ready for Flowella, in order, each linking to the detailed guide.
Setting up Meta is the part of Flowella onboarding that surprises most teams. There are eight discrete steps, each of which Meta gates separately, and missing one usually means you cannot move forward until you go back and complete it. This page is the map.
If you already have a WhatsApp Business Account (WABA) that is verified, billed, and approved to send messages, you do not need to start here — jump straight to [Connect Flowella to HubSpot](/hubspot/setup) and pick up the integration steps. Everything below is for teams setting Meta up from scratch.
## The sequence
A **business portfolio** (formerly called a "Business Manager" account) is the top-level container Meta uses to group your business assets — Facebook pages, ad accounts, WhatsApp Business Accounts, and so on. Most agencies and product companies already have one; if you don't, you create it at business.facebook.com.
Detailed walkthrough coming soon. For now, follow Meta's own guide and confirm your **15- or 16-digit business portfolio ID** afterwards.
Meta needs three things on the portfolio before it will let you do anything serious:
* A **main contact person and email address**
* The **legal operating name** of your business
* The **registered legal address** of your business
These have to match public records (Companies House in the UK, the equivalent registry in your country). Mismatches are the most common reason verification stalls.
Meta runs an automated check against the information above plus public records and your website. The **Start Verification** button appears in your portfolio's Security Centre once the business info is complete — except in newly created portfolios, where it can stay greyed out until a "dummy" asset (typically a Meta App) is attached.
See [Business information & verification](/meta/business-verification) for the full procedure including the Start Verification workaround.
A **WABA** is the WhatsApp-specific container that sits inside your portfolio. It holds your phone numbers, your business profile, and your message templates. You can create a new WABA via Flowella's Embedded Signup during onboarding, or attach an existing one if you already have it.
You need a real, working phone number that is not already registered with the consumer WhatsApp app or the WhatsApp Business app. Mobile numbers and landlines both work; toll-free, freephone, and IVR-routed numbers do not. See [Phone numbers explained](/meta/phone-numbers) for the full eligibility rules and the verification options (SMS or voice call).
Your **display name** is what customers see in WhatsApp instead of your phone number. It has to comply with Meta's naming policy and is reviewed for 1–3 business days before going live. Cover the rest of the profile (logo, description, business hours) at the same time. See [Display name & profile](/meta/profile-setup).
WhatsApp messages cost money beyond Meta's free tier. You need a card attached at the WABA level, set as **Default**, before Meta will continue delivering messages once you exhaust the free service tier. See [Meta payment method](/meta/payment-method).
Open Flowella's [Dashboard](/app/dashboard) and check the **Channels** section. A healthy WABA shows the green status indicator and an approved business verification badge. If anything is amber or red, follow the troubleshooting links inline to resolve it.
## Where each step blocks
Understanding which step gates which is the difference between a 30-minute setup and a three-day stuck ticket:
* **Steps 1–2 gate step 3.** You cannot start verification without a portfolio and complete business information.
* **Step 3 gates step 7.** You cannot add a working payment method to an unverified WABA, and unverified accounts cap at 250 unique recipients per 24 hours.
* **Step 5 gates step 6.** Display name approval runs against the phone number, so the phone number needs to be registered first.
* **Step 6 gates messaging.** Templates need an approved display name to send under the business name instead of the raw number.
* **Step 7 gates volume.** Without a Default card on the WABA, Meta will eventually pause message delivery.
## Co-existence: a shortcut if you already use the WhatsApp Business app
If you currently use the WhatsApp Business app on a phone with the number you want to keep, you can **co-exist** rather than fully migrate. Co-existence connects your existing number to the Business Platform while leaving the app working for 1:1 chats. It skips parts of steps 4–6. See [Co-existence](/meta/co-existence).
## After Meta is set up
With the Meta side complete, the rest is the Flowella integration:
* [Connect Flowella to HubSpot](/hubspot/setup) — link your HubSpot portal, choose Quick Start templates, finish onboarding
* [Workflow Actions](/hubspot/workflow-actions) — wire up triggers and actions in your HubSpot workflows
* [Templates](/app/templates) — build the first WhatsApp template you want to send
If you get stuck at any point, the [Troubleshooting](/troubleshooting/onboarding) page covers the most common Meta-side problems and their fixes.
# Create and manage a WhatsApp Business Account (WABA)
Source: https://knowledge.flowella.io/meta/whatsapp-business-account
Create a WhatsApp Business Account inside your Meta business portfolio, attach phone numbers, and understand the asset structure that Flowella connects to.
A **WhatsApp Business Account (WABA)** is the container that holds your WhatsApp-specific assets inside Meta's wider business structure. It is not the same as the WhatsApp Business app on your phone, and it is not the same as your business portfolio. Specifically, a WABA holds:
* One or more **phone numbers** registered to use WhatsApp
* The **business profile** (display name, logo, about text, business hours) for each number
* **Message templates** approved by Meta
* **Messaging limits** and quality ratings tracked per phone number
* **Payment settings** for WhatsApp Business Platform charges
Flowella connects to one or more WABAs through Meta's Embedded Signup. Each connected WABA appears as a channel in your Flowella org.
## When you need to create a new WABA
Most teams need exactly one WABA. Create more only when you have a clear reason:
* **Different legal entities** — if you operate multiple businesses under separate companies, each needs its own WABA in its own business portfolio
* **Strict separation between markets** — some teams keep a separate WABA per country to simplify reporting and tax accounting
* **Sandbox environment** — a separate WABA for testing avoids polluting your production analytics
If you're tempted to create a WABA per brand or per product, look at multiple **phone numbers within one WABA** first. That gets you per-number display names and templates without splitting your portfolio in two.
## Create a WABA
The smoothest path is to create it via Flowella's Embedded Signup flow during onboarding. Meta's flow handles WABA creation, phone number addition, and Flowella's connection in one sequence.
In Flowella, begin the Meta connection by clicking **Connect WhatsApp Business**. Meta's Embedded Signup launches in a popup.
Pick this option when Meta asks. (Choose **Use existing** instead if you already have a WABA in your portfolio that you want to attach.)
Provide:
* **WABA name** — internal label only, not customer-facing. "Acme Marketing WhatsApp" is fine.
* **Timezone** — affects reporting and message-window calculations.
* **Currency** — the currency Meta will bill you in for WhatsApp charges. **This cannot be changed later**, so pick the one you want invoices in.
Either:
* **Use an existing number** that isn't currently on the WhatsApp app or another API provider. See [Phone numbers](/meta/phone-numbers) for eligibility.
* **Pick a Meta-provided number** — actually, Meta no longer provides numbers; you bring your own.
Verify the number via SMS or voice call when prompted.
The display name is what customers see in WhatsApp instead of the raw phone number. Meta reviews it for 1–3 business days. See [Display name & profile](/meta/profile-setup) for the naming rules.
Meta returns you to Flowella, which records the WABA and phone number as a connected channel.
## Find your WABA ID
You'll sometimes need the WABA ID for Meta support tickets or troubleshooting. It's a 15- or 16-digit number distinct from your business portfolio ID.
To find it:
1. Go to **Meta Business Suite → Settings → Accounts → WhatsApp accounts**.
2. Click the WABA name.
3. The ID appears in the details panel that opens on the right ("ID: 123456789012345").
In Flowella, the same ID is shown in **Settings → Meta** next to each connected WABA.
## Add a phone number to an existing WABA
WABAs can hold up to 25 phone numbers each. To add another:
In Meta Business Suite, go to **WhatsApp Manager → Phone numbers → Add phone number**.
The number must be eligible (see [Phone numbers](/meta/phone-numbers)).
Receive the 6-digit code and enter it.
Each phone number has its own display name, profile, and templates. The display name must be approved by Meta before the number can send under the business name.
Back in Flowella, open **Settings → Meta** and click **Refresh channels**. The new number appears as an additional channel under the same WABA.
## Migrate a WABA between portfolios
Moving a WABA from one business portfolio to another is possible but slow:
1. Both portfolios must be **business-verified**.
2. The source portfolio admin initiates the request via Meta Business Suite.
3. Meta reviews the request, which can take 1–2 weeks.
4. After approval, the WABA moves to the destination portfolio. Phone numbers, templates, and messaging limits travel with it.
This is the path for company acquisitions, agency-to-client handovers, or restructuring exercises. For a same-portfolio WABA reorganisation, no migration is needed.
## What sits inside a WABA vs at the portfolio level
| Asset | Lives in | Notes |
| ---------------------- | ------------ | ------------------------------------------------------------ |
| Phone numbers | WABA | Up to 25 per WABA |
| Message templates | WABA | Submitted per WABA; not shared across WABAs |
| Display names | Phone number | Each number has its own display name, reviewed independently |
| Business profile | Phone number | Per-number logo, description, business hours |
| Quality rating | Phone number | Green/Yellow/Red, tracked per number |
| Messaging limits | Phone number | Tier 1–4, see [Messaging limits](/meta/messaging-limits) |
| Payment method | WABA | See [Meta payment method](/meta/payment-method) |
| Business verification | Portfolio | Verifying one portfolio covers all WABAs in it |
| Ad accounts (for CTWA) | Portfolio | Separate from WhatsApp billing |
## Related guides
* [Business portfolio](/meta/business-portfolio) — the parent container the WABA sits inside
* [Phone numbers](/meta/phone-numbers) — eligibility for the numbers you attach
* [Display name & profile](/meta/profile-setup) — the customer-facing name on each number
* [Messaging limits](/meta/messaging-limits) — how Tier 1–4 work and how to graduate
* [Meta payment method](/meta/payment-method) — the card Meta bills against
# Set up Flowella with the onboarding setup guide
Source: https://knowledge.flowella.io/onboarding
Use Flowella's auto-tracked onboarding checklist to connect Meta and HubSpot, configure your inbox, and launch your first WhatsApp send in 13 steps.
![Flowella recommended setup guide]()
When you sign in to Flowella for the first time, you're sent straight to the **Setup guide** — a single page at `/{org}/onboarding` that tracks every action you need to complete before going live. The guide watches your org's state in the background and ticks off each step as you complete it, so you can leave at any time and return to exactly the right place.
You can re-open the setup guide at any time from the left-hand sidebar entry **Setup guide**.
## How the setup guide works
* **Auto-detected progress.** Every step has a check that runs against your account — connect a WABA, add a payment method, install the HubSpot app, and the step turns green on its own. No "Mark as complete" buttons.
* **First-sign-in redirect.** New sign-ins land on the setup guide automatically until every required step is done.
* **Progress bar.** A live counter at the top shows how many of the 13 steps you've cleared.
* **Continue later.** Click **Continue later** at any point to return to the dashboard — your progress stays exactly where it was.
* **Per-step help.** Each step has a help tooltip that links straight to the matching knowledge-base page. If a step turns red, the tooltip explains why.
* **Completion celebration.** A confetti animation fires when the last step turns green, and the sidebar entry drops off automatically once you're fully onboarded.
The setup guide is **org-wide**, not per-user. Any admin can pick up where another admin left off — useful when WhatsApp setup and HubSpot setup are owned by different people.
## The 13 steps
The guide groups steps under three headers: **Connect**, **Configure**, and **Launch**. Each one links to a focused page in the knowledge base if you need more detail.
### Connect
Sign up at [app.flowella.io](https://app.flowella.io/). This step is already complete by the time you see the guide.
Click **Connect WhatsApp Business** to launch Meta's Embedded Signup. Choose or create your business portfolio, WABA, and phone number, and confirm Flowella's permissions. See [Setup sequence](/meta/setup-sequence).
Add a Visa, Mastercard, or Amex to your WABA and confirm it carries the **Default** badge. Meta — not Flowella — bills WhatsApp conversation charges to this card. See [Meta payment method](/meta/payment-method).
Run the HubSpot OAuth flow to link your portal. Flowella confirms with **Connected to HubSpot** and your Portal ID. See [HubSpot setup](/hubspot/setup).
Install Flowella from the HubSpot marketplace so the workflow actions, contact properties, and timeline events become available in your portal.
Add the **Flowella Channel** to HubSpot's conversations inbox so WhatsApp threads land alongside email, chat, and calls. Inbound WhatsApp is published to the channel, and outbound replies from the HubSpot inbox are relayed back to WhatsApp. See [Custom channel](/hubspot/custom-channel).
### Configure
Add the rest of your team under **Settings → Team** with the right role (Owner, Admin, or Member). See [Team](/settings/team).
Confirm the organisation name, business email, and content/export language under **Settings → Organization**. See [Organization](/settings/organization).
Flowella auto-provisions three reopen templates — Service, Update, and Offer — used by Smart Reply and the **Send WhatsApp Reply** workflow action. Review the wording and confirm at least one is **Approved** and enabled. See [Reply templates](/settings/reply-templates).
Build a Meta-approved WhatsApp template. The guide's CTA deep-links straight into the **Meta Library** gallery, where you can search Meta's prebuilt utility templates and tick several at once to create them as local drafts in one click. From there, edit, personalise, and publish. The step ticks off as soon as one template reaches the **APPROVED** state.
You can also switch to the **Flowella Templates** tab for curated starters, or start from a blank editor. See [Templates](/app/templates).
### Launch
From **Templates → your template → Send tab → Test Template**, send a test to your own number to confirm everything renders correctly.
Wire your template into a HubSpot workflow with the **Send WhatsApp Template** or **Send WhatsApp Reply** action. See [Workflow actions](/hubspot/workflow-actions).
Trigger a workflow against a real contact, or run a bulk send from the Send tab. The guide marks itself complete once the first non-test outbound message is delivered.
## What happens after completion
* The **Setup guide** entry disappears from the sidebar.
* The next sign-in goes straight to the dashboard.
* You can still re-open the guide from the in-app search at any time — every step continues to reflect live state, so it doubles as a health check if anything later changes (for example, the Meta payment method is removed).
* An **optional re-engagement tip** appears once, alongside the completed guide. Flowella auto-provisions a re-engagement template for closed WhatsApp windows, so no extra setup step is required — the tip just points you to the one-tap **Re-engage** action in the [Inbox](/app/inbox) for when a chat window has closed. Dismiss it with **Got it** and it won't come back.
## What's next
Build, test, and bulk-send Meta-approved WhatsApp templates.
Triggers and actions that wire WhatsApp into HubSpot workflows.
Open/Unseen + All/Pending tabs, Smart Reply, typing indicators.
Service / Update / Offer reopen templates and how they're managed.
Bring WhatsApp into the HubSpot conversations inbox.
Meta permissions, payment method, and HubSpot install issues.
# Flowella Data Security: Encryption, Storage, and GDPR
Source: https://knowledge.flowella.io/security/data-security
Learn how Flowella handles your data with AES-256 encryption, UK-based infrastructure, GDPR compliance, and strict access controls.
Flowella is committed to protecting your data with robust security and privacy measures. In practice, this means storing only the information needed to run your WhatsApp flows, securing everything with strong encryption, and hosting all infrastructure in a trusted UK-based cloud environment. Flowella is fully GDPR compliant, retaining data only as long as necessary and honouring all individual rights requests to ensure your customers' data stays private and protected.
## Key security properties
All data stored in Flowella's databases is encrypted at rest using **AES-256**. All data in transit — including WhatsApp messages, API calls, and web traffic — is secured using **TLS/HTTPS**.
Access to production systems is restricted to a small number of authorised team members, and only for legitimate operational reasons. Flowella uses **role-based access control**, requires **multi-factor authentication** for administrative access, and maintains **audit logs** of all administrative actions.
All of Flowella's infrastructure runs in **Microsoft Azure's UK South region** (London). Flowella does not use any third-party processors for messaging or infrastructure — everything runs on its own isolated Azure environment, including direct communication with WhatsApp's official Business API.
Flowella is built around GDPR principles: data minimisation, purpose limitation, and transparency. Personal data is never sold, shared with third parties, used for profiling, or used for Flowella's own marketing. All GDPR-defined individual rights are supported.
## Data handling and storage
Flowella practices **data minimisation** — it only collects and stores what is necessary to provide the service.
**What is stored:**
* **WhatsApp phone numbers** (and basic identifiers such as profile names) are stored to manage conversations and opt-outs. This allows Flowella to recognise returning users, maintain context, and honour opt-out requests. This data is held securely and can be deleted or anonymised when it is no longer needed.
**Message content policy:**
By design, Flowella avoids storing WhatsApp message content unless it is genuinely necessary. Where the platform you are integrating with provides suitable message storage, Flowella passes messages through and relies on that system as the source of truth.
If your connected platform does not provide adequate message storage, Flowella can store message content on your behalf as a fallback. A common example is logging WhatsApp conversations into HubSpot when your subscription does not support custom channels in the Conversations Inbox. Custom channels in HubSpot are only available on **Sales Hub Professional/Enterprise** and **Service Hub Professional/Enterprise**. If you are on a lower tier and still need reliable message history, you can enable message storage in Flowella. In that case, messages are encrypted, retained only as long as needed for your operational and compliance requirements, and can be deleted on request.
## Infrastructure and data residency
All of Flowella's infrastructure is hosted in **Microsoft Azure's UK South region** (London), keeping your data within the United Kingdom in an enterprise-grade cloud environment. Flowella maintains full control over its platform and does not use any third-party processors for messaging or infrastructure. Flowella communicates directly with WhatsApp's official Business API without relying on external messaging gateways. By keeping all data and operations self-contained in Azure, Flowella reduces exposure to outside parties and ensures consistent security and compliance.
## Encryption
All stored data is encrypted at rest using **AES-256**. All data in transit — including WhatsApp messages, API calls, and web traffic between Flowella, WhatsApp, and your devices — is secured using **TLS/HTTPS**. Whether your data is being saved or transmitted, it is always encrypted and protected from unauthorised access.
## Access controls
Access to your data within Flowella is tightly restricted:
* Only a small number of authorised Flowella team members (select engineers or support staff) can access production systems or databases, and only for legitimate operational reasons such as troubleshooting an issue you reported.
* **Role-based access control** ensures each team member has only the minimum permissions necessary.
* **Multi-factor authentication** is required for all administrative access.
* All administrative access to servers and databases is **logged and audited**.
* Staff are trained in confidentiality and data protection best practices.
Flowella also follows industry best practices for hardening its application and infrastructure, including keeping software up-to-date with security patches, using firewalls and network security measures, continuously monitoring systems for suspicious activity, and maintaining an incident response plan.
## Data retention and deletion
Flowella retains personal data only for as long as necessary to serve its intended purpose:
* WhatsApp contact information (phone numbers) is stored only while needed for active flows and customer interactions.
* Message content is not stored beyond the moment of processing by default.
* When a contact is no longer required or you stop using Flowella, that contact's data is deleted or anonymised as part of regular clean-ups or upon your request.
* If you cancel your Flowella account, all personal data held about your account and your WhatsApp contacts is securely removed from Flowella's systems, except for data Flowella is legally required to retain (such as minimal billing records).
You can request deletion of specific contact data or all personal data associated with your account at any time by contacting Flowella support. If one of your end-users submits a data subject access request (DSAR) or requests erasure of their information, Flowella will help you fulfil it promptly — for example, by removing a specific WhatsApp number from its database.
## GDPR compliance
Flowella is designed and operated to fully comply with the **General Data Protection Regulation (GDPR)** and similar data privacy laws. Key commitments:
* **Data minimisation** — only the data needed to deliver the service is collected and processed.
* **Purpose limitation** — data is only processed for the specific purpose of delivering the Flowella service. It is never used for profiling, Flowella's own marketing, or any other secondary purpose.
* **No third-party sharing** — personal data is never sold or shared with third parties.
* **Individual rights** — Flowella supports all GDPR-defined rights: access, rectification, erasure, restriction of processing, data portability, and objection. You and your end-users can exercise these rights and Flowella will assist in fulfilling them quickly and transparently.
* **Lawful processing** — personal data is handled lawfully, fairly, and transparently at all times.
## Related
Consent capture, automatic keyword opt-outs, and the audit trail.
Create, rotate, and revoke keys. Audit log on every change.
HMAC signing, replay protection, and delivery logs.
How to triage when something is wrong on Flowella, Meta, or HubSpot.
# Account security: passwords, passkeys, and sessions
Source: https://knowledge.flowella.io/settings/account
Manage sign-in security for your Flowella account: passwords, passkeys, backup sign-in methods, active sessions, and signing out of every device at once.
![Flowella account settings]()
The **Settings → Account** screen is where you manage the security side of your Flowella user — how you sign in, your backup sign-in methods, and signed-in sessions. It is separate from your [Profile](/settings/profile) (name, avatar, locale) and from organization-level settings.
If you signed up using a magic link or SSO, Flowella may show a banner that reads:
> You are signed in without a password. Add one for backup sign-in.
That banner links here. Adding a password or passkey gives you a backup way in if email delivery is delayed or you lose access to the original sign-in method.
## Opening Settings → Account
From the left navigation click **Settings**, then choose **Account** under the **Personal** section of the settings sidebar.
## Sign-in methods
Flowella supports three ways to sign in. You can have more than one active at a time — they're cumulative, not exclusive.
### Magic link (default)
Flowella emails a one-time sign-in link when you enter your email on the login page. The link is valid for a short window and can only be used once.
Magic link is always available — you cannot disable it. For full details, see [Logging in to Flowella](/account/login).
### Password
Click **Set password** (or **Change password** if one already exists) to manage a password for your account.
**Password requirements**
* At least 12 characters.
* A mix of letter cases and at least one number or symbol.
* Cannot match your last 5 passwords.
After a successful password change, Flowella signs out all other sessions on your account and sends an `AUTH_PASSWORD_CHANGED` notification to your email.
If you signed up via magic link and have never set a password, the button reads **Set password** instead of **Change password**. This is the recommended backup sign-in method.
### Passkeys
If passkeys are available for your account, you'll see a **Passkeys** section listing devices that have a registered passkey, with the option to register a new one or remove an existing one.
Passkeys use your device's biometric or hardware authentication (Touch ID, Face ID, Windows Hello, hardware security key) so you don't need to type a password or wait for a magic link.
## Active sessions
The **Active sessions** panel lists every device currently signed in to your account, with:
* Device and browser fingerprint
* IP address (truncated)
* Last activity timestamp
* A **Sign out** action
Sign out individual sessions if you see one you don't recognise. **Sign out of all sessions** revokes every session except the one you're using.
If you suspect a session you don't recognise, sign out of it, change your password, and contact support so we can audit the account.
## Email address
Your email is the primary identifier for your Flowella account and the address the magic link is sent to.
Your email address is **not changeable** from this screen — contact support if you need to change it, so we can verify the new address and migrate any pending invites.
## Deleting your account
To delete your Flowella user account, contact support. Account deletion is separate from removing yourself from an organization — see [Team](/settings/team) for the workspace-level action.
## Related
Password reset, magic link mechanics, and the bot-protection check.
Display name, avatar, phone number, and UI locale.
Choose which events deliver to email and the in-app feed.
Workspace-level membership and roles.
# Manage Flowella REST API keys
Source: https://knowledge.flowella.io/settings/api-keys
Create, view, rotate, and revoke API keys for the Flowella REST API from Settings → API keys, including scopes, expiry, and best practices for safe storage.
![Flowella API keys]()
API keys let scripts, no-code tools, and your own backend services call the Flowella REST API on behalf of your organisation. This page covers how to manage keys from the in-app **Settings → API keys** screen.
For what the API can do, see the [API reference](/api-reference/introduction).
## Who can manage API keys
Only the **Owner** or **Admin** roles see Settings → API keys. Members do not have access to this screen and cannot call API endpoints.
## Creating an API key
From the left navigation, go to **Settings → API keys**.
Give the key a **label** that describes what it's for (for example, `n8n production`, `analytics export script`). Labels are visible only inside Flowella — they're not sent in API requests.
By default, keys inherit the full set of API endpoints available to your plan. You can optionally restrict a key to a subset of scopes — for example, **read-only analytics** or **messages: send only**.
Flowella shows the secret token **exactly once** in a confirmation modal. Copy it now — you cannot view it again. If you lose it, you must revoke the key and create a new one.
The secret is shown only once. Flowella stores a hashed copy and cannot recover the plaintext. Treat keys like passwords — never commit them to source control, never paste them into chat or shared docs.
## Using a key
Pass the key as a bearer token on every request:
```bash cURL theme={null}
curl https://api.flowella.io/v1/messages \
-H "Authorization: Bearer flwl_live_..." \
-H "Content-Type: application/json"
```
```js Node.js theme={null}
await fetch("https://api.flowella.io/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ /* ... */ }),
});
```
```python Python theme={null}
import os, requests
requests.post(
"https://api.flowella.io/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}",
"Content-Type": "application/json",
},
json={"...": "..."},
)
```
See the [API reference](/api-reference/introduction) for endpoint details, rate limits, and error codes.
## Viewing existing keys
The Settings → API keys list shows each key's:
* **Label**
* **Prefix** (first eight characters, like `flwl_live_a1b2c3`) — useful for matching against logs.
* **Scope**
* **Created at** and **created by**
* **Last used at** — updated on every successful request.
* **Status** — active or revoked.
The plaintext secret is never displayed after creation.
## Rotating a key
There's no in-place rotate — you create a new key and revoke the old one once your service has switched over.
Follow the Create flow above to mint a new key with the same scope.
Update your service (or n8n workflow, Postman environment, etc.) to use the new bearer token.
Watch the new key's **Last used at** field — it updates within a minute of the first call.
Click **Revoke** on the previous key. From that point any request using the old secret returns `401 Unauthorized`.
## Revoking a key
Click **Revoke** on the row, then confirm in the dialog. Revocation is **immediate** — in-flight requests using that key may complete, but the next request returns `401`.
A revoked key cannot be reactivated. The row remains visible in the list (greyed out, with the revocation timestamp) so you have an audit trail.
## Audit log
Every **create**, **revoke**, and (where enabled) **scope change** event is written to the org audit log with your user, IP, and trace context. If your plan or contract includes the audit log feature, you can review API-key activity there.
## Common questions
There is no hard limit on hobby or paid plans, but very large numbers of active keys (50+) make rotation and review hard. Use one key per integration rather than one per developer.
Keys do not expire automatically. We recommend rotating them at least every 12 months and immediately if a key may have been exposed.
Currently keys are scoped to the **organisation**, not a specific channel. Channel-level scoping is on the roadmap. In the meantime, choose the active channel via the request payload or path.
Revoke it immediately from this page. Create a replacement with the same scope. Check the audit log for any requests that used the key in the time it was exposed, and rotate any downstream secrets that key may have created (for example, webhook signing keys).
## Related
Auth, errors, rate limits, and pagination.
Push events to your own systems instead of polling.
Only Owners and Admins can manage API keys.
Audit log coverage for key create / revoke events.
# Create PDF document templates
Source: https://knowledge.flowella.io/settings/document-templates
Build the PDF templates that HubSpot's Generate Document workflow action renders — headings, paragraphs, tables, spacers, and contact property tokens.
The **Settings → Document templates** screen is where you create and manage the PDF templates that the [Generate Document](/hubspot/workflow-actions#generate-document) HubSpot workflow action renders. Each template defines the layout of a PDF and the contact properties to fill it with.
## Opening Document templates
From the left navigation click **Settings**, then choose **Document templates** under the **Integrations** section of the settings sidebar.
You need the **Owner** or **Admin** role to create, edit, or delete document templates. Members can view the list.
## Building a template
A template has a **Name** and a **Template JSON** definition. The definition sets an optional document title and a list of blocks rendered top to bottom:
| Block | Renders as |
| ----------- | ---------------------------------- |
| `heading` | A heading line |
| `paragraph` | A body text paragraph |
| `table` | A table built from rows of cells |
| `spacer` | Vertical whitespace between blocks |
Insert contact properties anywhere in the title, heading text, paragraph text, or table cells with double-brace tokens in the `contact.` form, such as `{{contact.firstname}}`. When the Generate Document action runs, Flowella replaces each token with the enrolled contact's value.
```json theme={null}
{
"title": "Letter for {{contact.firstname}}",
"blocks": [
{ "type": "heading", "text": "Hello {{contact.firstname}}" },
{ "type": "paragraph", "text": "Email: {{contact.email}}" },
{ "type": "spacer" },
{
"type": "table",
"rows": [
["Name", "{{contact.firstname}} {{contact.lastname}}"],
["Phone", "{{contact.phone}}"]
]
}
]
}
```
Click **Create template** to save it. To change an existing template, pick it from the **Templates** list, edit the name or JSON, and click **Save changes**.
## Using a template in HubSpot
Each row in the **Templates** list shows the template ID with a **Copy ID** button. Copy it and paste it into the **Document template ID** field of the **Generate Document** action in your HubSpot workflow.
When the workflow runs, Flowella renders the template with the enrolled contact's properties, saves the PDF to your HubSpot files, and returns the file URL and HubSpot file ID for later workflow steps. See [Generate Document](/hubspot/workflow-actions#generate-document) for the action's full configuration.
## Related
The workflow action that renders these templates.
The companion action that reads documents into contact properties.
# Notification preferences
Source: https://knowledge.flowella.io/settings/notification-preferences
Choose which Flowella events deliver to your in-app feed and email inbox, manage digests, and review which alerts are mandatory for security and billing.
![Flowella notification preferences]()
Notification preferences let you tune which Flowella events show up in your in-app feed and which arrive by email. Preferences are **per-user**, not per-organisation — each user manages their own.
For the full list of events Flowella can emit, see [Notification events](/app/notification-events). For the in-app feed itself, see [Notifications](/app/notifications).
## Opening Settings → Notification preferences
From the left navigation, go to **Settings → Notifications**.
## How preferences are structured
Preferences are grouped by **category**.
Sign-in, password changes, new-device alerts.
Invoices, trial lifecycle, usage thresholds.
Submission, approval, rejection, re-categorisation, pause/disable, and quality drops.
Sync results, publish events.
Connection state, sync failures.
Channel connections, verification, quality drops.
Long-running job completion.
Inside each category, every event has two toggles:
* **In-app** — shows in the bell icon feed at `/notifications`.
* **Email** — sends to your verified profile email.
Toggle each independently. Changes save automatically.
## Mandatory categories
Some categories cannot be disabled. The toggles are still shown so you can see they exist, but they're greyed out with an explanation.
| Category | Why it's mandatory |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Authentication (`AUTH_*`) | Security. You always need to know about password changes, magic links, and new-device sign-ins. |
| Billing operational (`BILLING_PAYMENT_FAILED`, `BILLING_SUBSCRIPTION_CANCELLED`, etc.) | Org continuity. Missing a failed payment can interrupt service. |
| Usage hard cap (`USAGE_HARD_100`) | Service quality. You need to know when overage applies or, on trial, when sends are blocked. |
Other categories — usage soft alerts, template lifecycle events, HubSpot sync events — are optional.
## Org-wide operational email
Some org-level events (failed payments, subscription cancellation, trial expiry) are delivered both to **your personal email** and to a **single org-wide operational address**. The org-wide address is configured separately:
**Settings → Organisation → Notifications email**
Set this to your billing or operations team alias so critical events reach someone even when individual users are out of office.
## Daily reminder sweep
Flowella runs a daily sweep that re-surfaces high-impact unread notifications — for example, an unread `TEMPLATE_REJECTED` or `HUBSPOT_SYNC_FAILED` that has been sitting for more than 24 hours. The sweep respects your preferences: if you've turned off email for that category, the reminder is in-app only.
You cannot disable the sweep itself, but you can disable individual category reminders by turning off the underlying event.
## Quiet hours and digests
There is currently **no quiet-hours or digest mode** — every triggered notification is delivered immediately on the channels you've enabled. If you need to silence Flowella outside business hours, the practical workaround is to filter the `notifications@flowella.io` sender into a folder in your email client.
Quiet hours and a daily digest mode are on the product roadmap.
## Common questions
Most often: your profile email is unverified, or the message landed in spam. Check **Settings → Profile** for the verification status, and search your spam folder for `notifications@flowella.io`. If the email is verified and not in spam, check whether the event's email toggle is on.
No — preferences are strictly per-user. If you want a teammate to receive an event, they need to be a member of the org with the relevant role and they manage their own preferences.
Preferences apply across every org you're a member of. There is no per-org override yet. Roadmap.
See [Notification events](/app/notification-events) for the full catalogue with payload shapes.
## Related
The full catalogue of events with channels and mandatory flags.
The in-app feed these preferences control.
Push the same events to your own systems instead.
Verify your email address to receive notification emails.
# Organization settings: workspace name and language
Source: https://knowledge.flowella.io/settings/organization
Manage your Flowella workspace name, business email address, default content language, and other organisation-wide settings from Settings → Organization.
![Flowella organisation settings]()
Your **organization** (sometimes called a workspace) is the top-level container in Flowella. Everything you create — templates, forms, channels, opt-outs, API keys, team members, and the HubSpot connection — belongs to an organization.
A single Flowella account can belong to multiple organizations. Each organization has its own settings, billing, and team. The **Settings → Organization** screen is where the org-wide details live.
## Who can change organization settings
| Role | Can edit organization settings |
| ---------- | -------------------------------------------------------- |
| **Owner** | Yes — including the organization name and business email |
| **Admin** | Yes |
| **Member** | No — the fields are read-only |
For the full role breakdown, see [Team and roles](/settings/team).
## Opening Settings → Organization
From the left navigation click **Settings**, then choose **Organization** under the **Workspace** section of the settings sidebar.
## What you can change
### Organization name
The human-readable name for your workspace. It appears:
* In the org switcher when you belong to more than one Flowella organization
* On Stripe invoices and receipts
* On audit log entries and outbound webhook payloads
We recommend the legal name of the business that owns the WhatsApp Business Account, so invoices line up with your accounting records.
Renaming the organization does **not** change your subdomain or any deep links. The internal organization ID stays the same, so existing API keys, webhook subscriptions, and HubSpot connections continue to work.
### Business email
The email address Flowella uses for **billing and transactional notices** — invoices, payment failure alerts, subscription state changes, and Meta-related billing events.
* This is the org-level address, **not** an individual user's account email. Use a shared inbox (for example `billing@yourcompany.com`) so cover is maintained when people leave.
* If you leave the field empty, Flowella falls back to the **Owner's** profile email.
* This address does **not** receive product notifications — those follow each user's [notification preferences](/settings/notification-preferences).
Most finance teams want billing email separate from the person who set the org up. Set the business email to your accounts inbox to avoid invoices being missed when staff change.
### Content & export language
The default language for **customer-facing content** generated by Flowella, including:
* Default copy in system-sent emails to your customers (for example, opt-out confirmation emails where applicable)
* Headers and labels on CSV/XLSX exports from the inbox, analytics, and forms
* Default locale used when no template-level language override is set
Available languages match Flowella's supported UI locales:
* English (en)
* Español (es)
* Türkçe (tr)
* Deutsch (de)
* Ελληνικά (el)
* Français (fr)
* Italiano (it)
* Português (pt-BR)
* العربية (ar) — draft
This is the **organization default**. Individual templates and Flow forms can override it per send — see [Template reference](/app/template-reference). Each user's UI language is still controlled by their own [profile locale](/settings/profile).
Arabic operational copy (system emails, in-app notifications) is still being reviewed. Where a translated string is missing, Flowella falls back to English so customers always receive a legible message. Exports and headers respect the selected language once available.
## Saving changes
Click **Save changes** at the bottom of the screen. Updates take effect immediately:
* The new organization name shows in the switcher on next page load.
* Stripe customer records are updated within a few seconds.
* The new content language applies to the next export or system email — already-queued items keep the old language.
## Related
Invite teammates and manage roles for this workspace.
Plan, payment method, and invoices for this organization.
Connect and manage the WhatsApp Business Account attached to this org.
Your personal account details — separate from organization-level settings.
# Settings overview
Source: https://knowledge.flowella.io/settings/overview
A map of every screen in Flowella's Settings area — personal account, billing, developer tools, workspace, team, integrations, and notification preferences.
![Flowella settings]()
The **Settings** area in Flowella is split into five sections that mirror the in-app sidebar. Personal sections apply to your user account; Workspace, Billing, Developer, and Integrations apply to the whole organization.
## Personal
Settings that apply to your individual Flowella user, not the organization.
Display name, avatar, phone number, and UI locale.
Choose which Flowella events deliver to your in-app feed and email.
Password, passkeys, active sessions, and backup sign-in.
## Billing
Subscription, invoices, and conversation usage for the organization.
Plan, payment method, invoices, and subscription state.
Current month's conversation count, allowance, and caps.
For plan limits and the relationship between Flowella's subscription and Meta's per-conversation fees, see [Plans and limits](/account/plans-and-limits) and [Pricing and conversation categories](/account/pricing-and-conversation-categories).
## Developer
Programmatic access to your Flowella organization.
Create, rotate, and revoke keys for the Flowella REST API.
Outbound webhooks: endpoints, signing secrets, event subscriptions, retries.
## Workspace
Organization-wide identity and membership.
Workspace name, business email, and default content language.
Members, roles, invitations, and ownership transfer.
## Integrations
External platforms connected to your Flowella organization.
Connected WABAs and phone numbers, token health, re-authorisation.
Portal connection, scopes, and the property mapping that powers workflows.
PDF templates rendered by the Generate Document HubSpot workflow action.
## Who can change what
| Setting area | Owner | Admin | Member |
| ------------------------------------------ | ----- | ---------------------- | --------- |
| Personal (Profile, Notifications, Account) | Self | Self | Self |
| Billing | Yes | Read-only | Read-only |
| Usage | Read | Read | Read |
| API keys, Webhooks | Yes | Yes | Read-only |
| Organization | Yes | Yes | Read-only |
| Team | Yes | Yes (except Owner row) | Read-only |
| Integrations | Yes | Yes | Read-only |
| Document templates | Yes | Yes | Read-only |
See [Team](/settings/team) for the full role definitions.
# User profile settings in Flowella
Source: https://knowledge.flowella.io/settings/profile
Update your display name, avatar, phone number, locale, time zone, and password for your personal Flowella account from the Settings → Profile screen.
Your profile settings hold your personal account details: display name, avatar, email, phone number, and role. Open them from **Settings → Profile**.
![Flowella profile settings]()
Your profile is the user-level record Flowella uses for sign-in, mentions in the inbox, and recipient details on notifications. Each Flowella user has one profile, even if you're a member of multiple organisations.
## Opening Settings → Profile
From the left navigation, click your avatar → **Profile**, or go to **Settings → Profile**.
## What you can change
### Display name
The name shown to teammates in the inbox, notifications feed, audit log, and team list. We recommend your full first and last name — initials make it harder for teammates to attribute conversations.
### Avatar
Click your current avatar to upload a new one.
* Accepted formats: **JPEG, PNG, WebP**.
* Maximum file size: **2 MB**.
* Recommended: a square image at least 256 × 256 px.
Avatars are uploaded server-side and stored in Flowella's Azure Blob storage with a signed URL. Direct browser uploads to Azure are not used (this avoids CORS and firewall edge cases). If the upload fails, the original avatar is preserved.
### Phone number (optional)
You can add a phone number in international format (E.164, for example `+447700900123`). The country picker resolves the format for you.
The phone number is used to:
* Prefill the Stripe Checkout form when starting or changing a subscription.
* Sync your contact details to Stripe so invoices show the right phone number.
* (Optional, opt-in) Receive WhatsApp notifications about your account.
Leaving the phone field empty is fine — Stripe Checkout will simply ask for it at the point of payment.
### Locale
Sets the language for the Flowella UI and emails. Available locales:
* English (en, default)
* Español (es)
* Türkçe (tr)
* Deutsch (de)
* Ελληνικά (el)
* Français (fr)
* Italiano (it)
* Português (pt-BR)
* العربية (ar) — draft
Changing your locale takes effect immediately, including across soft navigation between screens — the choice is written to your user record and to the `NEXT_LOCALE` cookie so it follows you across devices and reloads.
**Arabic is a draft locale.** The interface switches to right-to-left when you pick `ar`: the root `` element flips to `dir="rtl" lang="ar"`, page layout uses logical inline start/end spacing, and directional icons (chevrons, arrows, send, reply, panel toggles) mirror automatically. Universal glyphs like search, check, and the WhatsApp mark are not mirrored. Translation is still in progress, so some strings may fall back to English until the Arabic message pack is finalised.
### Password
Click **Change password** to set a new password. You'll be asked to enter your current password first.
If you signed up via magic link or SSO and have never set a password, the section instead reads **Set password** — useful as a backup sign-in method.
**Password requirements**
* At least 12 characters.
* A mix of letter cases and at least one number or symbol.
* Cannot match your last 5 passwords.
After a successful password change, Flowella signs out all other sessions on your account and sends a `AUTH_PASSWORD_CHANGED` notification to your email.
## Email address
Your email address is the primary identifier for your Flowella account. It is **not changeable** from this screen — contact support if you need to change it, so we can verify the new address and migrate any pending invites.
## Linked WhatsApp account
If you have linked a personal WhatsApp number for notifications, it's shown here with an **Unlink** action. Unlinking stops Flowella from sending notifications to that number but does not affect your Flowella sign-in.
## Sessions
The **Active sessions** panel lists every device currently signed in to your account, with:
* Device and browser fingerprint
* IP address (truncated)
* Last activity timestamp
* A **Sign out** action
Sign out individual sessions if you see one you don't recognise. **Sign out of all sessions** revokes every session except the one you're using.
If you suspect a session you don't recognise, sign out of it, change your password, and contact support so we can audit the account.
## Related
Password reset, magic link, and the bot-protection check.
Choose which events deliver to your in-app feed and email.
What each role can do across the org.
Your phone number is reused on Stripe checkout for prefill.
# Edit Service, Update, and Offer reply templates
Source: https://knowledge.flowella.io/settings/reply-templates
Edit the framing text for Flowella's Service, Update, and Offer reopen templates used by the Reply tab and HubSpot's Send WhatsApp Reply action.
Flowella maintains three system **reopen templates** — **Service**, **Update**, and **Offer** — that wrap free-text replies into an approved WhatsApp template when the 24-hour customer service window has closed. The **Settings → Reply templates** screen lets you edit the framing text around each one without leaving Flowella.
These templates power the [Reply tab in the Inbox](/app/inbox#reply-tab-smart-reply) and the [Send WhatsApp Reply](/hubspot/workflow-actions#send-whatsapp-reply) HubSpot workflow action.
## How reopen templates work
Each reopen template has three locked variables:
| Variable | Filled with |
| -------- | -------------------------------------------------------- |
| `{{1}}` | The contact's first name |
| `{{2}}` | Your business name |
| `{{3}}` | The free-text reply typed in the inbox or HubSpot action |
You can change the **framing text** around these variables (greeting, sign-off, business-specific phrasing). The variables themselves cannot be moved or removed — they're how Flowella injects the actual reply.
The three template kinds map to Meta's [Utility template](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/utility-templates/utility-templates) category and are billed as Utility conversations when used to reopen a closed window.
| Kind | Meta template name | Best for |
| ----------- | ------------------------- | --------------------------------------------- |
| **Service** | `flowella_reopen_service` | Day-to-day customer service replies (default) |
| **Update** | `flowella_reopen_update` | Status updates, order/appointment changes |
| **Offer** | `flowella_reopen_offer` | Win-back replies that include a promotion |
## Opening Reply templates
From the left navigation click **Settings**, then choose **Reply templates** under the **Workspace** section of the settings sidebar.
You need the **Owner** or **Admin** role to edit reply templates. Members can view the screen but not save changes.
## Auto-provisioning
You don't need to create reply templates manually. Flowella submits the three reopen templates to Meta automatically as soon as your organization has a **Meta-connected WhatsApp channel**:
* Opening the Inbox while the window is closed triggers provisioning for any missing kinds.
* Opening **Settings → Reply templates** does the same.
* An hourly worker sweeps any org still showing **Not provisioned** and submits the missing templates.
Templates are **not** created before WhatsApp is connected — there's nothing to provision until Meta has a phone number to submit them against.
## Editing the framing text
Open the **Service**, **Update**, or **Offer** card. Each card shows the current body text with `{{1}}`, `{{2}}`, `{{3}}` highlighted in place.
Change the text around the variables. The variables themselves are locked — you can move text around them but can't delete or reorder them.
Click **Save**. Flowella submits a **new version** of the template to Meta (for example, `flowella_reopen_service_v2`). The previously approved version stays live until Meta approves the new one.
The card shows the version state machine: **Draft → Pending → Approved** (or **Rejected**). Status is reconciled from Meta when you open the page, in case a webhook delivery was missed.
## System-managed and undeletable
The three reopen templates are **system-managed** by Flowella. In the main [Templates](/app/templates) catalogue they appear with a **System** badge on both the list and card views, and the **Delete** action is removed. Opening one in the template editor also disables the delete button with a tooltip explaining that system re-engagement templates can't be removed.
Use the toggle on each card in Reply templates to stop a kind being used instead of deleting it.
## Reset to default
Each card has a **Reset to default** action that restores Flowella's stock framing text and re-submits to Meta. Use this if a custom version is rejected and you need to recover quickly.
## Enable / disable
Use the toggle on each card to disable a kind you don't want the Reply tab or HubSpot action to use. The Reply tab will fall back to the next enabled kind (Service → Update → Offer); if none are enabled the composer is disabled outside the window and prompts you to pick a specific template via **Send template**.
## Conversation costs
* **Inside the 24-hour window:** standard session messaging applies (no template charge for text).
* **Outside the 24-hour window:** the reopen template opens a Utility conversation per Meta pricing — currently \~\$0.045 per send, depending on country. See [Pricing and conversation categories](/account/pricing-and-conversation-categories) for the breakdown.
## Related
Where the reopen templates are used in the agent UI.
HubSpot workflow action that uses the same reopen templates.
Create and submit standard WhatsApp templates.
Utility vs Marketing vs Service conversation pricing.
# Team members and roles in Flowella
Source: https://knowledge.flowella.io/settings/team
Invite teammates to your Flowella workspace, manage roles and permissions, handle pending invitations, and remove members from the Settings → Team screen.
![Flowella team settings]()
Flowella organizations are multi-user. The **Settings → Team** screen lists everyone with access to the current workspace, lets you invite new people, and shows pending invitations. This page covers the screen end to end, plus what each role can do.
## Opening Settings → Team
From the left navigation click **Settings**, then choose **Team** under the **Workspace** section of the settings sidebar.
## Roles at a glance
Flowella has three roles:
| Role | Best for | Key capabilities |
| ---------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Owner** | The person who set up the org | Everything an Admin can do, plus billing, deleting the org, and transferring ownership |
| **Admin** | Operators who run the WhatsApp programme | Manage channels, templates, opt-outs, integrations, API keys, webhooks, and team members |
| **Member** | Everyone else on the team | Use the inbox, view templates and analytics, send messages on connected channels — cannot manage billing or workspace settings |
Owners and Admins are functionally similar day-to-day. The main difference is **billing and org-level destructive actions**, which only Owners can do.
Roles apply at the **organization** level. The same person can have a different role in a different Flowella organization.
## Members table
The **Members** table at the top of the screen lists everyone with access to the workspace, with four columns plus a remove action:
| Column | What it shows |
| ---------- | -------------------------------------------------------------------------------------------- |
| **Name** | The display name from the member's [profile](/settings/profile) |
| **Email** | The account email the member signs in with |
| **Role** | Owner, Admin, or Member |
| **Joined** | The date the member accepted the invite (or for the Owner, the date the org was created) |
| **Remove** | Removes the member from the organization — see [Removing a member](#removing-a-member) below |
You cannot remove yourself or the Owner from this table. To leave an org you don't own, ask another Owner or Admin to remove you. To remove the Owner, transfer ownership first.
## Inviting people
You need the **Owner** or **Admin** role to invite teammates.
In the **Invite people** section, type the person's work email in **Email address**.
Pick **Member** (default), **Admin**, or **Owner** from the **Role** dropdown. The helper text under the dropdown describes what each role can do.
Click **Send invite**. Flowella emails the invitee a link of the form `https://app.flowella.io/join?code=…` and adds them to **Pending invitations**.
Promoting someone to **Owner** at invite time is uncommon — most teams invite as Member or Admin, then transfer ownership later through the role change flow.
### Accepting an invite
If you have been invited:
1. Open the invite email and click **Accept invite**.
2. If you do not yet have a Flowella account, you will be asked to create one with the same email the invite was sent to.
3. If you already have an account, sign in. Flowella will add you to the organization and apply the role from the invite.
Invite links are one-time use and expire after a period set by Flowella. If your link has expired, ask the person who invited you to send a new one.
## Pending invitations
The **Pending invitations** section lists invites that have been sent but not yet accepted. If there are no outstanding invites, the section reads **No pending invitations.**
For each pending invite you can:
* **Resend** the invite email (useful if the original was filtered to spam).
* **Revoke** the invite. Revoking immediately invalidates the join link — the invitee can no longer use it.
Invitations expire automatically after the Flowella invite TTL elapses. Expired invites stay visible in this section until you revoke them or resend a new link.
## Changing a role
Owners and Admins can change another member's role:
1. Click the member's row in the **Members** table.
2. Pick the new role.
3. Save.
You cannot change your own role. To transfer ownership, the current Owner must promote a teammate — see below.
## Transferring ownership
Only the current **Owner** can transfer ownership.
1. Promote the new Owner to **Owner** from **Settings → Team**.
2. The previous Owner is automatically demoted to **Admin**.
Each org has exactly one Owner at a time.
## Removing a member
Owners and Admins can remove members by clicking **Remove** on the member's row. Removing a member:
* Immediately revokes their access to the org. Any active session is terminated on the next request.
* Does **not** delete the messages they sent or templates they created — those stay in the org.
* Does **not** affect their account in other Flowella organizations.
* Does **not** automatically revoke API keys they created. Rotate or revoke keys separately — see the tip below.
* Reassigns any open inbox conversations they were the assignee on to **Unassigned**, so other agents can pick them up.
When a teammate leaves the company, remove them from the org **and** rotate any API keys they created. See [API keys](/settings/api-keys) for the rotation steps.
## Related
Workspace name, business email, and default content language.
Rotate or revoke any keys a leaving teammate created.
Only Owners can change billing — covered here.
Each user manages their own name, avatar, password, and sessions.
# Usage
Source: https://knowledge.flowella.io/settings/usage
Track your current month's WhatsApp conversation count, see how much of your allowance remains, and understand soft and hard caps.
![Flowella usage and billable messages]()
The Usage page shows how much of your plan's monthly allowance you've consumed, broken down by channel and by day. Use it to forecast overage, spot anomalies, and confirm exactly when your billing cycle resets.
For what counts as a conversation, and how Meta and Flowella charges line up, see [Pricing & conversation categories](/account/pricing-and-conversation-categories) and [Plans & limits](/account/plans-and-limits).
## Opening Settings → Usage
From the left navigation, go to **Settings → Usage**.
## What the page shows
### Current cycle
The top of the page shows your **current billing cycle** — start date, end date, days remaining, and a progress bar of conversations consumed against your plan's monthly allowance.
The cycle is based on your **subscription anniversary**, not the calendar month. If you signed up on the 14th, your cycle resets on the 14th of each month.
| Plan | Cycle | Allowance |
| ---------- | ------------------- | ---------------------------------------------- |
| Free Trial | 14 days from signup | 5,000 outbound messages (hard cap, no overage) |
| Starter | Monthly | 2,000 conversations |
| Pro | Monthly | 5,000 conversations |
| Enterprise | Per contract | Custom |
### Conversation counter
The big number under the progress bar is **conversations used this cycle**. It updates in near real time. Every conversation that opens or closes ticks the counter within a few seconds.
On paid Starter and Pro, the counter reads **`{used} of {cap} included`**. Once usage passes the included amount, the page adds the note **"Usage beyond the included amount is billed as metered overage"** and the counter keeps climbing past 100%. On the Free trial, the counter reads **`{used} of {cap} messages`** and stops sends at 100%.
Below the counter:
* **Inbound conversations** — started by a contact messaging you first.
* **Outbound conversations** — initiated by a template send.
* **Free Service-window replies** — counted toward your Flowella allowance even when Meta charges \$0 (see [Pricing & conversation categories](/account/pricing-and-conversation-categories)).
Only conversations Meta marks billable on its delivery webhook count against your allowance. Template sends that Meta rejects or fails to deliver (for example, error 131049) do not tick the counter and are not billed as overage.
### Per-channel breakdown
If your org has multiple WhatsApp channels, the page shows a table with one row per channel:
* Channel name and WABA / phone number ID
* Conversations used this cycle
* 7-day trend sparkline
* Percentage of total org usage
This is useful for orgs that run multiple brands or markets and want to attribute usage to a specific number.
### Daily chart
A bar chart of conversations per day for the current and previous cycle, so you can spot spikes and weekly patterns. Hover any bar for the exact count.
### Historical cycles
A table of the last 12 billing cycles with usage and any overage. Each row links into the matching invoice in Stripe.
## Soft caps and hard caps
| Cap | What triggers it | What happens |
| -------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`USAGE_SOFT_50`** | You've used 50% of your plan's allowance (or the trial's 5,000-message cap). | In-app and email alert. No restrictions. |
| **`USAGE_SOFT_80`** | You've used 80% of your allowance. | In-app and email alert. No restrictions. |
| **`USAGE_HARD_100`** | You've used 100% of your allowance. | On paid Starter and Pro: additional conversations continue to send and are billed as metered overage (see [Plans & limits](/account/plans-and-limits) for the per-conversation rate). On the Free trial: outbound sends are **blocked** until you upgrade. |
You can subscribe or unsubscribe from the soft alerts in [Settings → Notification preferences](/settings/notification-preferences). The hard-cap notification is mandatory.
## Allowance does not roll over
Unused conversations from this cycle **expire at the cycle reset**. They do not carry forward. If you regularly leave a large portion of your allowance unused, downgrading to a smaller plan is usually cheaper than absorbing the unused capacity.
See [Pricing & conversation categories](/account/pricing-and-conversation-categories#monthly-usage-does-not-roll-over) for more detail.
## Exporting
Click **Export** to download a CSV of:
* Current-cycle conversation totals (org + per channel + per day)
* The last 12 cycles' totals
* Any overage that has been billed
The CSV is useful for finance reconciliation against your Stripe invoices.
If your Stripe invoice and Flowella's usage counter disagree by more than a few conversations, check the **meter health** indicator on [Settings → Billing](/account/billing#usage-metering-and-stripe-meter-health). Persistent drift is usually a webhook problem and should be raised with support.
## Related
What each plan includes and how overage is priced.
What counts as a conversation and why Meta charges are separate.
Manage subscription and view invoices.
Subscribe to 50% / 80% usage alerts.
# Webhooks
Source: https://knowledge.flowella.io/settings/webhooks
Configure outbound webhooks from Settings → Webhooks: endpoint URLs, signing secrets, event subscriptions, retries, and delivery logs.
![Flowella outbound webhooks]()
Webhooks let Flowella push events to your own systems in real time — for example, notify your CRM when a WhatsApp message is delivered, or kick off a background job when a HubSpot form sync fails. This page covers the in-app **Settings → Webhooks** screen.
For the payload schemas of each event, see [Webhooks reference](/api-reference/webhooks).
## Who can manage webhooks
Only **Owner** and **Admin** roles see Settings → Webhooks. Other roles do not have access.
## Adding a webhook endpoint
From the left navigation, go to **Settings → Webhooks**.
Enter the public HTTPS URL Flowella should POST events to. HTTP (without TLS) is not accepted.
Choose one or more event types — for example, `message.delivered`, `template.approved`, `flow.sync.failed`. The full event list is on [Webhooks reference](/api-reference/webhooks). You can subscribe to all events with a single checkbox.
Flowella shows the signing secret **once** at the end of the create flow. Save it in a secure store — you'll use it to verify the HMAC signature on every incoming request.
Use the **Send test** button to fire a synthetic event at your endpoint. The delivery log records the result so you can confirm your handler is wired up before going live.
## Signing and verification
Every webhook request includes an `X-Flowella-Signature` header with an HMAC-SHA256 signature of the raw request body, computed with your endpoint's signing secret. Verify it before trusting the payload:
```js Node.js theme={null}
import crypto from "crypto";
function verify(rawBody, signature, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
```
```python Python theme={null}
import hmac, hashlib
def verify(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
```
```ruby Ruby theme={null}
require "openssl"
def verify(raw_body, signature, secret)
expected = OpenSSL::HMAC.hexdigest("sha256", secret, raw_body)
Rack::Utils.secure_compare(expected, signature)
end
```
```php PHP theme={null}
function verify(string $rawBody, string $signature, string $secret): bool {
$expected = hash_hmac('sha256', $rawBody, $secret);
return hash_equals($expected, $signature);
}
```
The request also includes:
* `X-Flowella-Timestamp` — the Unix timestamp at send time. Reject requests where the timestamp is more than 5 minutes in the past or future to prevent replay attacks.
* `X-Flowella-Event` — the event type (for example, `message.delivered`).
* `X-Flowella-Delivery` — a unique delivery ID, useful for deduplication.
## Retries and back-off
If your endpoint returns a non-2xx status code (or times out after 10 seconds), Flowella retries with exponential back-off:
| Attempt | Delay after previous |
| ----------- | -------------------- |
| 1 (initial) | — |
| 2 | 30 seconds |
| 3 | 2 minutes |
| 4 | 10 minutes |
| 5 | 1 hour |
| 6 | 6 hours |
| 7 (final) | 24 hours |
After 7 failed attempts the delivery is marked **failed** and dropped. The endpoint is **not** automatically disabled — you can still receive future events on the same endpoint.
If 100 consecutive deliveries fail, Flowella **auto-pauses** the endpoint and sends a `WEBHOOK_PAUSED` notification. Resume it from the row's menu once you've fixed the underlying issue.
## Delivery log
Each endpoint row expands into a delivery log showing the last 7 days of attempts:
* **Event type and ID**
* **Status** — success, failed, retrying
* **Attempt number**
* **Response code and duration**
* **Response body** (first 1 KB)
* **Sent at**
Click any delivery to view the full request and response, or to **redeliver** it manually.
## Managing endpoints
From the endpoint row menu you can:
* **Edit** — change the URL or event subscriptions. (The signing secret stays the same.)
* **Rotate secret** — generate a new signing secret. The old secret stops working immediately, so coordinate the change with your handler.
* **Pause** — temporarily stop deliveries without losing the configuration.
* **Resume** — turn a paused endpoint back on.
* **Delete** — remove the endpoint and its delivery history.
## Common questions
Yes — there's no hard limit. Most orgs have 1–3 endpoints (production, staging, and an internal log sink). Keep the count low so the events fan out predictably.
The API is **pull** — your code asks Flowella for state. Webhooks are **push** — Flowella tells your code when state changes. Use webhooks for anything you'd otherwise poll for.
Webhook payloads include conversation IDs, contact phone numbers, message content, and template names. Treat the secret and the endpoint URL as sensitive. Restrict your endpoint to accept POST from Flowella's IP range if your infrastructure allows it.
Use a tunnel tool (ngrok, Cloudflare Tunnel) to expose your localhost endpoint to a public HTTPS URL, then point a **Test endpoint** at it. Don't put a tunnel URL into your production endpoint — they expire.
## Related
Event types, payload schemas, and headers.
The other half of programmatic integration.
Errors, rate limits, and pagination.
The same events delivered into the in-app feed and email.
# Actions locked by billing
Source: https://knowledge.flowella.io/troubleshooting/billing-locked-actions
What to do when sending WhatsApp messages, publishing templates, or using the Flowella API is blocked by a subscription state — and how to restore access.
Some actions in Flowella require an active subscription. If you see "Subscription required", a `402` error from the API, or buttons that are greyed out with a billing tooltip, this page explains what's locked and how to unlock it.
For the full subscription model, see [Billing](/account/billing).
## What gets locked
When a subscription becomes **past due** or **cancelled** (and the paid period has ended), the following are blocked:
* Sending new WhatsApp messages from the inbox
* Sending templates from HubSpot workflows
* Bulk template sends via the API (`POST /v1/templates/send`)
* Publishing or syncing new WhatsApp Flows
* Submitting new templates to Meta
* Adding new channels or phone numbers
These remain available so you can recover:
* Signing in
* Viewing existing data — contacts, conversations, opt-outs, analytics, templates
* The Billing page
* Inbound message receipt (incoming WhatsApp messages still arrive in your inbox; you just can't reply until billing is fixed)
## Subscription states that lock actions
| State | What's happening | What you'll see |
| ----------------------- | ------------------------------------------------------ | ------------------------------------------------- |
| **Past due** | A card payment failed and Stripe is retrying | Yellow banner on every page; some actions blocked |
| **Canceled (in grace)** | Subscription is cancelled but paid period hasn't ended | Yellow banner; full access until the period ends |
| **Canceled (expired)** | Paid period has ended | Red banner; paid actions blocked |
| **Trialing** | Paid plan in free-trial period | Full access; no banner |
| **Active** | Paid plan in good standing | Full access; no banner |
## How to restore access
Only the **Owner** of the org can change billing.
Sign in and go to **Settings → Billing**.
Click **Manage subscription**. Stripe opens in a new tab.
* For **past due**, update the failing card.
* For **expired**, pick a plan and complete checkout.
Stripe webhooks update Flowella within seconds. The Billing page polls automatically; refresh other pages to clear the banner.
## API behaviour
The REST API returns a `402 Payment Required` response with this envelope when an action is blocked by billing:
```json theme={null}
{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Your subscription does not allow this action."
}
}
```
In your client, treat `402` as a recoverable state — surface it to the org Owner so they can fix billing rather than retrying automatically.
## Common confusion
### "I just paid — why is it still locked?"
Stripe webhooks are usually instant, but very rarely take a minute or two. If the banner persists for more than five minutes after a successful payment, refresh the page or click **Manage subscription** to confirm the status in Stripe.
### "Why can my teammate still send messages?"
They can't — but if the action is queued client-side, the UI may show success momentarily before the server rejects it. Send attempts will land in the inbox as **Failed** with a billing reason.
### "We paid but a specific feature is still locked"
Check that your **plan tier** includes that feature. See [Plans and limits](/account/plans-and-limits). For example, the Starter plan does not include the public REST API — API access starts on Pro.
## Still locked after paying?
Capture the following before contacting [support](https://flowella.io/support):
* A screenshot of **Settings → Billing** showing the current state
* The Stripe receipt or invoice ID for the most recent payment
We can reconcile manually if a webhook didn't land.
## Related
Manage subscription, payment method, and Stripe meter health.
What each plan includes and how trial caps differ from paid overage.
See where you are in the current billing cycle.
How Meta charges and Flowella usage interact.
# Healthy ecosystem engagement (error 131049)
Source: https://knowledge.flowella.io/troubleshooting/healthy-ecosystem-engagement
Why a marketing template can fail with "not delivered to maintain healthy ecosystem engagement", even on a first message, and how to reach the contact.
If a WhatsApp template fails to send with the message **"This message was not delivered to maintain healthy ecosystem engagement"** and the code `131049`, this page explains what is happening and how to get through.
The short version: this only affects **Marketing** templates. It is a per-recipient limit set by WhatsApp, not a problem with your account or your number. The quickest way through is to send a **Utility** template, such as an opt-in confirmation, or to have the contact message you first.
## What the error means
`131049` is WhatsApp's per-user marketing limit. WhatsApp caps how many marketing messages a person receives across every business, based on how that person engages with marketing and how full their inbox is. When someone is at that cap, the next marketing template is not delivered and Meta returns `131049`.
Two things tend to surprise people:
* **It can happen on the very first message you send.** The limit belongs to the recipient, not to your history with them, so a contact can already be at their cap from marketing they received from other businesses.
* **You cannot check a contact's remaining capacity in advance.** WhatsApp does not expose it, so there is no reliable way to predict the error before you send.
This is specific to the **Marketing** category. **Utility** and **Authentication** templates are not subject to this limit, which is why switching the first message to a utility-style template usually gets through.
## How to reach the contact
Utility templates, such as opt-in confirmations, order updates, reminders, and account notices, are not capped by `131049`. If your first contact is a non-promotional Utility message rather than a marketing one, it will generally deliver. Keep the wording strictly non-promotional, or Meta may re-classify it as Marketing. See [Template reference](/app/template-reference).
When a contact sends you any message, it opens a 24-hour window. Marketing templates sent inside that window do not count towards the recipient's limit, so they deliver normally. A [click-to-chat link or QR code](/campaigns/click-to-chat) is the easiest way to prompt that first inbound message.
Do not resend the same marketing template straight away. Retrying within 24 hours will only fail again and can distort your delivery statistics. Wait at least 24 hours, or use one of the two routes above.
## Is it my number or the recipient?
It is the recipient. `131049` is decided by the recipient's marketing engagement, not by your number's quality rating or verification status. Sending the same template to a different contact will usually succeed.
The **"Finish Meta business verification"** banner you may see in Flowella is unrelated to this error. That banner concerns your overall [messaging limits](/meta/messaging-limits), which govern how many unique people you can message per day, not the per-recipient marketing cap behind `131049`. Completing verification is still worthwhile, but it will not stop this particular error.
## Showing Flowella on a live demo
If you hit this error while walking someone through Flowella, the cleanest fix in the moment is to ask the person receiving the message to send any reply to the number first. A click-to-chat link or QR code makes that a single tap. That opens the 24-hour window immediately, and the template will then send.
## Errors that look similar but are not the same
The contact has chosen to stop marketing messages from your business. Do not resend. Confirm their status under **Contacts → Opt-outs**. See [Opt-outs](/app/opt-outs) and [Opt-out not honoured](/troubleshooting/opt-out-not-honoured).
This one is about your number, not the recipient. It appears when previous messages were flagged. Check your number's quality and ease off marketing to disengaged contacts. See [Quality score](/meta/quality-score).
You are trying to send a free-form message outside the 24-hour window. Send an approved template instead. See [Messages not delivered](/troubleshooting/messages-not-delivered).
Still stuck? Gather the recipient's phone number, the timestamp of the failed send, and a screenshot of the failure reason, then contact [support](https://flowella.io/support).
# HubSpot sync failures
Source: https://knowledge.flowella.io/troubleshooting/hubspot-sync-failures
Diagnose missing HubSpot form submissions, stalled workflow actions, dedupe-suppressed template sends, and contact properties not reaching HubSpot.
Most HubSpot issues fall into one of three buckets: the **integration is disconnected**, a **field mapping is wrong**, or a **workflow action is misconfigured**. This page works through them in order.
For initial setup, see [HubSpot setup](/hubspot/setup). For workflow actions, see [Workflow actions](/hubspot/workflow-actions).
## 1. Check the connection
From the Flowella app, go to **Settings → HubSpot**.
A green **Connected** badge means the OAuth token is valid. A red **Reconnect** banner means the token has been revoked or expired.
Click **Reconnect** and run through HubSpot OAuth again. Then retry the failing action.
Common causes for a HubSpot connection going bad:
* The HubSpot user who authorised Flowella was removed from the portal.
* HubSpot rotated the token because it had not been used recently.
* A Super Admin disabled the Flowella integration in HubSpot's app settings.
## 2. Form submissions not appearing in HubSpot
If a contact completes a WhatsApp Flow but you can't see the submission in HubSpot:
### Field mapping mismatch
The Flow may include a field that doesn't map to a HubSpot property of a compatible type. Open the form on the [Forms](/app/forms) page and review the mapping for each field.
### Required field is empty
If a HubSpot form field is marked required and the WhatsApp Flow allowed the user to skip it, the submission will be rejected by HubSpot. Make the field optional in HubSpot, or required in the Flow.
### Phone number format
HubSpot is strict about phone format. See [Phone number format](/hubspot/phone-number-format) — most "missing contact" issues come down to E.164 vs national format.
### Lookup happens after the workflow action runs
If your HubSpot workflow runs immediately on form submission, race conditions can cause the workflow to fire before Flowella has finished writing the contact. Add a short delay (1–2 minutes) at the start of the workflow, or trigger off the contact property change instead of the form submission.
## 3. Workflow actions stalled or failing
If a HubSpot workflow that includes a Flowella action is stuck:
### Open the workflow's Action history
In HubSpot, find the contact, scroll to **Workflow History**, and click into the failing run. HubSpot shows the response Flowella returned for each action.
### Common error responses
| Error | What to do |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Channel not found` | The workflow points at a channel that no longer exists. Edit the action and pick a current channel. See [Multi-channel](/essentials/multi-channel). |
| `Template not approved` | The template referenced has changed status to `REJECTED`, `PAUSED`, or `DISABLED`. See [Template rejected](/troubleshooting/template-rejected). |
| `Contact opted out` | The contact has opted out on this channel. Honour the opt-out — do not work around it. |
| `Phone number invalid` | The contact's phone is not in E.164. See [Phone number format](/hubspot/phone-number-format). |
| `Subscription required` | Your Flowella plan does not include this action, or your subscription has lapsed. See [Billing](/account/billing). |
| `DUPLICATE_TEMPLATE_SEND_SUPPRESSED` | The same template was already sent to the same phone number inside Flowella's dedupe window. This is an intentional guard, not a delivery failure. See [Template send suppressed as duplicate](#template-send-suppressed-as-duplicate). |
### Send action failure codes
Failed **Send WhatsApp Template**, **Send WhatsApp Message**, and **Send WhatsApp Reply** rows on the HubSpot contact enrollment history show a specific Flowella failure reason and an error code. Use the code to jump to the fix.
| Error code | What it means | How to fix |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BODY_PARAMETER_COUNT_MISMATCH` | The template expects a different number of variables than the workflow action supplies. | Open the action in HubSpot and map exactly the variables the template defines. Unused Template Variable slots should be left blank; missing ones must be mapped. |
| `CONTACT_PHONE_MISSING` | The mapped **Contact Phone Number** property is empty on the enrolled contact. | Add a phone number to the contact, or change the action to map a different property that is populated. |
| `CONTACT_PHONE_INVALID` | The phone number is present but not in a valid international format. | Reformat to E.164 (for example `+447700900123`). See [Phone number format](/hubspot/phone-number-format). |
| `TEMPLATE_NOT_FOUND` | The selected WhatsApp template no longer exists in Flowella. | Edit the action and pick a current template. If the template was deleted, recreate it or select a replacement. |
| `TEMPLATE_WABA_MISMATCH` | The template belongs to a different WhatsApp Business Account than the channel the action is sending from. | Edit the action to select a template from the same WABA as the sending channel, or move the send to the channel that owns the template. |
| `FAILED` | Any other send failure. | Read the accompanying message on the row — it names the underlying cause (for example a Meta Graph error). Match it to a row in the [Common error responses](#common-error-responses) table above. |
### Template send suppressed as duplicate
If HubSpot shows a **Send WhatsApp Template** action completed with error reason `DUPLICATE_TEMPLATE_SEND_SUPPRESSED`, Flowella intentionally skipped the send because the same template was already sent to the same phone number inside its dedupe window.
The most common trigger is **two HubSpot contacts sharing a phone number** — for example a personal and a work record, or a household with one WhatsApp number — enrolling in the same workflow within seconds of each other. Only the first send goes to WhatsApp; the second is suppressed so the contact does not receive the same message twice.
Previously the second workflow action would sit in **Pending** for around an hour until HubSpot's callback timeout. Flowella now completes the callback immediately as a failure so the enrolled contact moves on to the next step (or the "action failed" branch) without waiting.
**How to tell it apart from a real failure:**
* **Suppressed as duplicate** — the error reason is exactly `DUPLICATE_TEMPLATE_SEND_SUPPRESSED`. The template did send to that phone number, just via a different enrolled contact. No action needed.
* **Genuine send failure** — the error will be a specific reason such as `Template not approved`, `Phone number invalid`, `Contact opted out`, or a Meta Graph error code. Follow the row in the table above.
If you legitimately need to send the same template to the same number twice (for example a re-confirmation after a long delay), space the enrolments out past the dedupe window or use a different template.
### Action exists but does nothing
If the workflow runs without errors but no message arrives, double-check:
* The action is enabled (not paused).
* The recipient is enrolled in the workflow at the right step.
* HubSpot's enrolment criteria still match the contact.
## 4. Sync direction confusion
Flowella sync is **bidirectional but partial**:
* WhatsApp Flow submissions → write contact properties to HubSpot.
* HubSpot workflow actions → send WhatsApp messages and templates.
* Inbound WhatsApp replies → log to the contact timeline (does not auto-update properties).
If you expected a free-form WhatsApp reply to update a property, that needs an extra step on your side — a HubSpot workflow that watches for the conversation event and parses the reply, or a custom integration via the [API](/api-reference/introduction).
## Still stuck?
Capture the following before contacting [support](https://flowella.io/support):
* The **last sync** timestamp from **Settings → HubSpot**
* The exact error message (or screenshot) Flowella or HubSpot returned
* The affected contact ID and workflow ID
# Messages not delivered
Source: https://knowledge.flowella.io/troubleshooting/messages-not-delivered
Diagnose outbound WhatsApp messages that never reach the recipient: failed sends, messages stuck on sent, missing read receipts, and Meta error codes.
If a message you sent isn't reaching the recipient, this page walks you through the most common causes in order of frequency.
## Where to look first
Open the [Inbox](/app/inbox) and find the conversation. Each outbound message shows a status:
| Status | Meaning |
| ------------- | ------------------------------------------------ |
| **Sent** | Flowella has handed the message to Meta |
| **Delivered** | Meta confirmed it reached the recipient's device |
| **Read** | The recipient opened it |
| **Failed** | Meta rejected it or could not deliver it |
If you see **Failed**, hover or click the message to see the failure reason. If you see **Sent** but never Delivered, work through the list below.
## Common causes
Work through these in order — they're listed by frequency.
Sending to an opted-out contact is blocked. Check **Contacts → Opt-outs** or the contact card in the inbox. See [Opt-outs](/app/opt-outs).
If the contact has not actually asked to opt out, an opt-out keyword in their reply (for example, "stop", "unsubscribe") may have triggered it automatically. Reach out via another channel to confirm intent before re-enabling.
You can only send free-form messages within 24 hours of the contact's last inbound message. Outside that window, you must use an approved **template**. See [Templates](/app/templates) and [Template reference](/app/template-reference).
If the message used a template, check the template's status under **Templates**. A template can move out of `APPROVED` due to recipient feedback or quality issues. See [Template rejected](/troubleshooting/template-rejected).
WhatsApp Business Platform messages can only be received on the regular WhatsApp consumer app. Numbers running the standalone WhatsApp Business app on the same device cannot receive API messages while the app is active.
Meta tracks a quality rating per phone number. Low quality reduces your daily messaging limit and can pause sends. Check **Settings → Meta** for the per-number quality indicator. If quality has dropped:
* Pause non-essential sends.
* Avoid sending Marketing templates to disengaged contacts.
* Wait 24–48 hours for the rating to recover.
If your Stripe subscription is past due or cancelled, sending is restricted. See [Billing](/account/billing). Restore payment and the restriction lifts within a few minutes.
Phone numbers must be in **E.164** form (`+447700900123`). A leading 0, a missing country code, or extra punctuation will cause Meta to reject the send. See [Phone number format](/hubspot/phone-number-format).
If the recipient has blocked you on WhatsApp, messages will report as **Sent** but never **Delivered**. There is nothing to fix on the Flowella side.
Check [Meta's WhatsApp Business API status](https://metastatus.com/whatsapp-business-api). If there is a live incident, sends will retry once the platform recovers.
## Still stuck?
Gather the following before contacting [support](https://flowella.io/support):
* The **conversation ID** or contact's phone number
* The **timestamp** of the failing send
* A screenshot of the message status
# Troubleshooting Common Onboarding Issues in Flowella
Source: https://knowledge.flowella.io/troubleshooting/onboarding
Fix the most common problems encountered during Flowella onboarding, including Meta permissions, payment setup, HubSpot access, and template approvals.
Most onboarding issues are caused by one of four things: missing Meta Business Manager permissions, an incomplete payment method setup, insufficient HubSpot permissions, or a misunderstanding about when WhatsApp message templates are required. The sections below cover each issue and how to resolve it.
If you work through the steps below and the issue persists, contact the Flowella support team. Include a description of the problem, any error messages you see, and the step in the onboarding flow where you are stuck.
This usually means your Meta user account does not have the right permissions on the Business Manager account you are trying to connect.
**What to check:**
* Confirm that you are a **Business Manager admin** for the Meta Business account you selected during onboarding. Only admins can grant the permissions Flowella needs.
* If you can see that permissions appear toggled off during the connection flow, do not skip or dismiss the screen. Select **Back**, then re-enter the step and enable all required scopes before continuing.
If you are not the Business Manager admin, ask the admin to either complete the connection themselves or grant you admin access before you try again.
If you see a warning about a missing payment method during or after onboarding, it means your WhatsApp Business account in Meta does not yet have a payment method on file. Without one, Meta will limit or block message delivery once your free tier is exhausted.
**How to fix it:**
Follow the full walkthrough in [Meta payment method](/meta/payment-method), which covers adding a card to the WABA and, critically, confirming it is set as the **Default** payment method on the WABA.
This payment method covers Meta's WhatsApp message delivery fees, which are separate from your Flowella subscription. See [Plans & Limits](/account/plans-and-limits) for more detail on how the two cost types work.
If no HubSpot portals appear when you try to connect your HubSpot account, your HubSpot user does not have the **Install App** permission required to authorise third-party integrations.
**How to fix it:**
* Ask a HubSpot **Super Admin** to either connect the Flowella app themselves or grant your user the Install App permission, then retry the connection.
Only Super Admins can grant Install App permissions in HubSpot. If you are unsure who your Super Admin is, check **HubSpot Settings → Users & Teams**.
WhatsApp restricts business-initiated messages to contacts who have not recently interacted with you. If you attempt to send a proactive message — for example, a follow-up or re-engagement — more than 24 hours after the last user-initiated message, WhatsApp requires you to use a pre-approved **message template**.
**How to fix it:**
* Create and submit your message templates for Meta approval via **Flowella → Templates**.
* Template approval typically takes a short time but is not instant. Submit templates before you need them.
Test your approved templates in a sandbox or with a test contact before using them in live campaigns. This lets you catch formatting issues or unexpected variable substitutions before they reach real users.
## Related
The happy-path setup guide this troubleshooter complements.
The order Meta steps need to happen in for verification to land.
Add the default card to your WABA.
OAuth connection, portal selection, and form discovery.
# Opt-out not honoured
Source: https://knowledge.flowella.io/troubleshooting/opt-out-not-honoured
Why a WhatsApp contact who opted out is still receiving messages from Flowella, and how to fix the cause without breaking the rest of your sends.
Flowella blocks outbound sends to opted-out contacts automatically — but the block is **per channel**. If a contact tells you they're still hearing from you after opting out, work through the checks below.
For how the opt-out list works in general, see [Opt-outs](/app/opt-outs). For multi-channel context, see [Multi-channel](/essentials/multi-channel).
## 1. Confirm the opt-out actually registered
Open **Contacts → Opt-outs** and search for the contact's phone number.
* **Listed, active**: Flowella will block sends from the channel where they opted out.
* **Listed, revoked**: A teammate cleared the opt-out, manually or via the API. Re-add it.
* **Not listed**: The opt-out never registered. See section 2.
## 2. The opt-out keyword wasn't recognised
By default, Flowella treats common keywords as opt-out triggers (for example `STOP`, `UNSUBSCRIBE`). The match is case-insensitive but typo-sensitive. If the contact wrote `please stop messaging me` rather than just `STOP`, no automatic opt-out fires.
You can:
* Manually add the contact to the opt-out list from the inbox or **Contacts → Opt-outs**.
* Add a quick-reply button to your templates that explicitly says "Unsubscribe" and routes to your opt-out handling.
## 3. The contact opted out on a different channel
Opt-outs are recorded **per WhatsApp channel** because consent is given to a specific business sender. If the same contact is messaged from two channels in your org and only opted out on Channel A, sends from Channel B continue.
Decide which model you want and apply consistently:
Replicate the opt-out across every channel using the API. Repeat for each channel. See the [opt-outs endpoint](/api-reference/openapi.json).
```bash cURL theme={null}
curl -X POST https://api.flowella.io/v1/opt-outs \
-H "Authorization: Bearer flo_…" \
-H "Content-Type: application/json" \
-d '{"action":"set","whatsappChannelId":"","phone":"+44…"}'
```
```js Node.js theme={null}
await fetch("https://api.flowella.io/v1/opt-outs", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
action: "set",
whatsappChannelId: "",
phone: "+44…",
}),
});
```
```python Python theme={null}
import os, requests
requests.post(
"https://api.flowella.io/v1/opt-outs",
headers={
"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}",
"Content-Type": "application/json",
},
json={
"action": "set",
"whatsappChannelId": "",
"phone": "+44…",
},
)
```
Keep opt-outs separate per channel. Make sure your privacy notice tells contacts that opting out of Brand A does not opt them out of Brand B.
## 4. A workflow re-enrols opted-out contacts
If a HubSpot workflow keeps trying to message the same opted-out person, the action will fail at the Flowella side (returning `Contact opted out`) — but the contact may still see the workflow attempt.
Add a HubSpot enrolment criterion that excludes contacts whose `WhatsApp opt-out` property is true. Update that property whenever Flowella records an opt-out using a webhook subscriber or a periodic sync.
Alternatively, subscribe to the [`optout.created` webhook](/api-reference/webhooks) and write back to HubSpot in real time.
## 5. The contact never opted in cleanly to begin with
This is a policy issue rather than a bug, but worth flagging: WhatsApp requires **explicit, unambiguous opt-in** before any business-initiated message. If the contact says "I never agreed to this", investigate how they ended up on your list. Add the opt-out, apologise, and review your collection process.
## 6. The block is working, but they still receive a final message in flight
Outbound sends are queued before the recipient list is finalised. A message that's already in Meta's send queue may still deliver in the seconds after an opt-out is recorded. This is rare and self-corrects within a minute.
## Still seeing messages reach an opted-out contact?
Capture the following before contacting [support](https://flowella.io/support):
* The contact's phone number
* The channel ID and name
* The exact send time
We can audit the send path end-to-end.
# Template rejected
Source: https://knowledge.flowella.io/troubleshooting/template-rejected
Why Meta rejects a WhatsApp message template, how to read the rejection reason in Flowella, and what to change in the template before resubmitting it.
Meta reviews every template you submit. Most rejections come down to a small set of recurring issues. This page covers the common ones and what to change before resubmitting.
For the format itself (categories, headers, buttons, variables) see [Template reference](/app/template-reference).
## Where to read the rejection reason
In Flowella, open **Templates** and find the rejected template. The rejection reason returned by Meta appears on the template page, usually as a short string like `INVALID_FORMAT` or a sentence explaining the issue.
## Common rejection reasons
You submitted a Marketing-style message under **Utility**. Common signs:
* Promotional copy ("Sale ends Friday", "Get 20% off")
* An offer or coupon
* Re-engagement messaging
Resubmit as **Marketing**. If the template is genuinely transactional (order updates, password resets, appointment reminders), keep it as Utility but tighten the copy.
Authentication templates can contain only the verification code and minimal supporting text. Anything that reads like marketing — branding statements, offers, links to your site — will be rejected. Strip back to the code, an expiry note, and "Do not share this code".
When you add a variable like `{{1}}`, Meta requires a sample value that matches what you'd really send. Common mistakes:
* A sample link that's a generic homepage when the body promises an order tracking page.
* A sample name with special characters that imply unsupported formatting.
* Samples that don't match the template's tone (e.g. `John` for a first name when the body addresses the recipient as "Customer").
Use realistic samples. For URLs, use a real production-style URL with placeholder IDs.
These get rejected fast:
* Excessive capitalisation (`FREE!!!`)
* Multiple exclamation marks
* "Click here" without context
* Over-promising language ("guaranteed", "100% off")
* Misleading urgency ("Last chance!" without a real deadline)
Rewrite as a calm, factual message. WhatsApp templates should read like a useful update, not a banner ad.
Variables must be sequential starting from `{{1}}`. `{{1}}` then `{{3}}` will be rejected. Renumber so they go `{{1}}`, `{{2}}`, `{{3}}` in order.
For IMAGE, VIDEO, and DOCUMENT headers, Meta tries to fetch the URL during review. If it 404s, redirects through a login page, or is blocked by your CDN to non-browser user-agents, the template is rejected. Host on stable infrastructure that allows Meta's crawler.
* Quick reply labels longer than 25 characters
* URL buttons whose URL pattern doesn't make sense (`https://example.com/{{1}}` with a sample of `not-a-path`)
* Phone buttons in non-E.164 format
Fix the offending button, leave the others in place.
A WABA cannot have two templates with the same `name` and `language`. If you re-submitted with the same name without removing the old one, the new one will be rejected. Either pick a new name, or delete the old version first.
Meta enforces a **30-day cooldown** on re-using a name after deletion. If you try to publish a template with the same name as one Meta is currently deleting, Flowella surfaces a cooldown-specific error so you know to either wait or pick a new name.
## Resubmitting
Open the rejected template in Flowella.
Click **Edit**.
Make the fix indicated by the rejection reason.
The template re-enters the `PENDING` state. Most resubmissions clear Meta's automated review within minutes, though some are routed for human review and can take up to 48 hours.
Keep working APPROVED templates untouched. Edit a copy when you want to make significant changes — that way your live sends keep working while Meta reviews the new version.
## Still rejected after fixing?
If the same template is rejected twice and you can't see why, contact [support](https://flowella.io/support) with:
* The template name and language
* The full rejection reason from Meta
* A screenshot of the template body, header, and buttons
We can often spot the issue quickly or escalate to Meta on your behalf.
## Related
Categories, headers, button rules, and variable syntax.
Sample values, fallbacks, and the rejection traps that come with them.
Edit and resubmit the rejected template.
Why category mismatches matter beyond just rejection.
# Flowella: HubSpot-powered WhatsApp Flows for marketers
Source: https://knowledge.flowella.io/what-is-flowella
Flowella converts your existing HubSpot forms into native WhatsApp Flows and syncs every response straight back into your CRM automatically.
Flowella is a SaaS platform that lets you turn your existing HubSpot forms into interactive WhatsApp Flows, then pushes every response straight back into HubSpot. You keep using the tools you already have to capture and store data — Flowella adds a fast, friendly WhatsApp experience on top.
## Why Flowella exists
Traditional web forms work fine until your audience is on mobile, distracted, on a slow connection, or simply reluctant to fill in yet another webpage. WhatsApp is where your customers already are. Meta's WhatsApp Flows feature lets you show native, structured forms inside the WhatsApp app itself. Flowella bridges those flows and the rest of your stack.
Flowella solves three problems:
1. **Rebuilding forms is painful.** You already have great forms in HubSpot. Recreating them in WhatsApp by hand is time-consuming and error-prone.
2. **Keeping data in sync is hard.** Even if you build WhatsApp journeys yourself, getting that data back into HubSpot reliably is a significant headache.
3. **Marketing and CRM teams are disconnected.** Marketers want better WhatsApp journeys. CRM teams want clean, consistent data. Flowella keeps both sides happy.
## How Flowella works
Flowella sits between your marketing stack and the WhatsApp Business Platform.
You authorise Flowella to access your HubSpot portal. This lets Flowella read the forms, properties, and objects you choose, and submit data back into HubSpot when a WhatsApp Flow is completed.
Flowella works with the official Meta WhatsApp Business Platform. You configure your WhatsApp sender and templates as usual, then use Flowella to power the form experience inside WhatsApp.
You pick a form or object in HubSpot and use Flowella to create a matching WhatsApp Flow. Questions, options, and validation are aligned with your existing data model.
Once your Flow is ready and approved, you can launch it from entry points such as WhatsApp ads, links, QR codes, chatbots, or agent replies.
When a customer completes the WhatsApp Flow, Flowella submits their responses to HubSpot. That can trigger any workflows, scoring rules, or automations you already have in place.
The result: a smooth, conversational experience for the user, with clean, structured data in your CRM.
## Key features
Create or configure WhatsApp Flows that mirror your HubSpot forms. Control input types, required fields, validation rules, and multi-step experiences.
Connect securely via OAuth. Map Flow fields to HubSpot form fields or properties, trigger existing HubSpot workflows on submission, and keep all data, reporting, and automation inside HubSpot.
Start with predefined templates for common scenarios — lead capture from ads, event registration, member onboarding, and NPS or feedback collection — then customise them for your brand and data model.
View incoming WhatsApp conversations in an inbox, respect opt-out keywords and preferences, and stay aligned with WhatsApp and privacy rules.
## Who Flowella is for
Flowella is designed for teams who want to engage customers on WhatsApp without leaving HubSpot behind:
* **Marketers** who want higher conversion rates and more engaging mobile journeys
* **CRM and operations teams** who care about clean data and reliable integrations
* **Support or member services teams** who want structured information before speaking to a customer
You do not need to be a developer to use Flowella. Technical teams can go deeper into configuration and automation, but most of the platform is accessible without writing any code.
## Example use cases
A HubSpot form for "Book a demo" is mirrored as a WhatsApp Flow. Prospects who click a click-to-WhatsApp ad can book in a few taps, and the submission lands directly in HubSpot.
A membership organisation sends renewal reminders by WhatsApp with a Flow that confirms key details and pushes updates into HubSpot automatically.
An event registration form lives in HubSpot, while late registrants complete a WhatsApp Flow that writes directly into the same list and triggers the same workflows.
In each case, HubSpot remains the single source of truth. Flowella provides the WhatsApp experience and the data bridge.
## What you need to get started
To use Flowella, you typically need:
* A HubSpot portal with forms and properties set up
* A WhatsApp Business account on the official Meta platform
* Permission to connect both systems
Once these are in place, you can start creating WhatsApp Flows that submit straight into HubSpot — often in under an hour.
Ready to connect your accounts? Follow the [onboarding guide](/onboarding) to create your Flowella account and link Meta and HubSpot.
## Related
Connect Meta and HubSpot and build your first flow.
How Flowella sits between HubSpot and the WhatsApp Business Platform.
OAuth, portal selection, and form discovery.
Trial, paid plans, and how monthly usage works.
# Outbound message analytics
Source: https://knowledge.flowella.io/api-reference/analytics/outbound-message-analytics
/api-reference/openapi.json get /v1/analytics
Aggregates outbound message counts and rates by status for a date range.
# Create or update contact
Source: https://knowledge.flowella.io/api-reference/contacts/create-or-update-contact
/api-reference/openapi.json post /v1/contacts
# List contacts
Source: https://knowledge.flowella.io/api-reference/contacts/list-contacts
/api-reference/openapi.json get /v1/contacts
# Set or clear per-channel WhatsApp opt-out
Source: https://knowledge.flowella.io/api-reference/contacts/set-or-clear-per-channel-whatsapp-opt-out
/api-reference/openapi.json post /v1/opt-outs
`action: set` creates or reactivates an opt-out for the given channel and phone. `action: clear` revokes it. Idempotent clears are safe.
# List conversations
Source: https://knowledge.flowella.io/api-reference/conversations/list-conversations
/api-reference/openapi.json get /v1/conversations
# Send WhatsApp text message
Source: https://knowledge.flowella.io/api-reference/messages/send-whatsapp-text-message
/api-reference/openapi.json post /v1/messages
# Ping (auth check)
Source: https://knowledge.flowella.io/api-reference/system/ping-auth-check
/api-reference/openapi.json get /v1/ping
Returns `ok` and the organization id for the resolved API key. Use to verify credentials.
# List WhatsApp templates
Source: https://knowledge.flowella.io/api-reference/templates/list-whatsapp-templates
/api-reference/openapi.json get /v1/templates
# Queue template send job
Source: https://knowledge.flowella.io/api-reference/templates/queue-template-send-job
/api-reference/openapi.json post /v1/templates/send
Accepts a bulk template send and processes it in the background. The request is validated at the door, queued durably, and returns `202 Accepted` immediately with a job id. Send an `Idempotency-Key` header to make retries safe: repeats of the same key within seven days return the original job id instead of sending the batch again. Without the header, Flowella derives a key from the request body, so an identical batch submitted twice in quick succession is not double-sent. Recipients are processed individually, so one invalid number does not block the rest of the batch.
# Outbound message analytics
Source: https://knowledge.flowella.io/api-reference/analytics/outbound-message-analytics
/api-reference/openapi.json get /v1/analytics
Aggregates outbound message counts and rates by status for a date range.
# Create or update contact
Source: https://knowledge.flowella.io/api-reference/contacts/create-or-update-contact
/api-reference/openapi.json post /v1/contacts
# List contacts
Source: https://knowledge.flowella.io/api-reference/contacts/list-contacts
/api-reference/openapi.json get /v1/contacts
# Set or clear per-channel WhatsApp opt-out
Source: https://knowledge.flowella.io/api-reference/contacts/set-or-clear-per-channel-whatsapp-opt-out
/api-reference/openapi.json post /v1/opt-outs
`action: set` creates or reactivates an opt-out for the given channel and phone. `action: clear` revokes it. Idempotent clears are safe.
# List conversations
Source: https://knowledge.flowella.io/api-reference/conversations/list-conversations
/api-reference/openapi.json get /v1/conversations
# Send WhatsApp text message
Source: https://knowledge.flowella.io/api-reference/messages/send-whatsapp-text-message
/api-reference/openapi.json post /v1/messages
# Ping (auth check)
Source: https://knowledge.flowella.io/api-reference/system/ping-auth-check
/api-reference/openapi.json get /v1/ping
Returns `ok` and the organization id for the resolved API key. Use to verify credentials.
# List WhatsApp templates
Source: https://knowledge.flowella.io/api-reference/templates/list-whatsapp-templates
/api-reference/openapi.json get /v1/templates
# Queue template send job
Source: https://knowledge.flowella.io/api-reference/templates/queue-template-send-job
/api-reference/openapi.json post /v1/templates/send
Accepts a bulk template send and processes it in the background. The request is validated at the door, queued durably, and returns `202 Accepted` immediately with a job id. Send an `Idempotency-Key` header to make retries safe: repeats of the same key within seven days return the original job id instead of sending the batch again. Without the header, Flowella derives a key from the request body, so an identical batch submitted twice in quick succession is not double-sent. Recipients are processed individually, so one invalid number does not block the rest of the batch.
# Outbound message analytics
Source: https://knowledge.flowella.io/api-reference/analytics/outbound-message-analytics
/api-reference/openapi.json get /v1/analytics
Aggregates outbound message counts and rates by status for a date range.
# Create or update contact
Source: https://knowledge.flowella.io/api-reference/contacts/create-or-update-contact
/api-reference/openapi.json post /v1/contacts
# List contacts
Source: https://knowledge.flowella.io/api-reference/contacts/list-contacts
/api-reference/openapi.json get /v1/contacts
# Set or clear per-channel WhatsApp opt-out
Source: https://knowledge.flowella.io/api-reference/contacts/set-or-clear-per-channel-whatsapp-opt-out
/api-reference/openapi.json post /v1/opt-outs
`action: set` creates or reactivates an opt-out for the given channel and phone. `action: clear` revokes it. Idempotent clears are safe.
# List conversations
Source: https://knowledge.flowella.io/api-reference/conversations/list-conversations
/api-reference/openapi.json get /v1/conversations
# Send WhatsApp text message
Source: https://knowledge.flowella.io/api-reference/messages/send-whatsapp-text-message
/api-reference/openapi.json post /v1/messages
# Ping (auth check)
Source: https://knowledge.flowella.io/api-reference/system/ping-auth-check
/api-reference/openapi.json get /v1/ping
Returns `ok` and the organization id for the resolved API key. Use to verify credentials.
# List WhatsApp templates
Source: https://knowledge.flowella.io/api-reference/templates/list-whatsapp-templates
/api-reference/openapi.json get /v1/templates
# Queue template send job
Source: https://knowledge.flowella.io/api-reference/templates/queue-template-send-job
/api-reference/openapi.json post /v1/templates/send
Accepts a bulk template send and processes it in the background. The request is validated at the door, queued durably, and returns `202 Accepted` immediately with a job id. Send an `Idempotency-Key` header to make retries safe: repeats of the same key within seven days return the original job id instead of sending the batch again. Without the header, Flowella derives a key from the request body, so an identical batch submitted twice in quick succession is not double-sent. Recipients are processed individually, so one invalid number does not block the rest of the batch.
# Outbound message analytics
Source: https://knowledge.flowella.io/api-reference/analytics/outbound-message-analytics
/api-reference/openapi.json get /v1/analytics
Aggregates outbound message counts and rates by status for a date range.
# Create or update contact
Source: https://knowledge.flowella.io/api-reference/contacts/create-or-update-contact
/api-reference/openapi.json post /v1/contacts
# List contacts
Source: https://knowledge.flowella.io/api-reference/contacts/list-contacts
/api-reference/openapi.json get /v1/contacts
# Set or clear per-channel WhatsApp opt-out
Source: https://knowledge.flowella.io/api-reference/contacts/set-or-clear-per-channel-whatsapp-opt-out
/api-reference/openapi.json post /v1/opt-outs
`action: set` creates or reactivates an opt-out for the given channel and phone. `action: clear` revokes it. Idempotent clears are safe.
# List conversations
Source: https://knowledge.flowella.io/api-reference/conversations/list-conversations
/api-reference/openapi.json get /v1/conversations
# Send WhatsApp text message
Source: https://knowledge.flowella.io/api-reference/messages/send-whatsapp-text-message
/api-reference/openapi.json post /v1/messages
# Ping (auth check)
Source: https://knowledge.flowella.io/api-reference/system/ping-auth-check
/api-reference/openapi.json get /v1/ping
Returns `ok` and the organization id for the resolved API key. Use to verify credentials.
# List WhatsApp templates
Source: https://knowledge.flowella.io/api-reference/templates/list-whatsapp-templates
/api-reference/openapi.json get /v1/templates
# Queue template send job
Source: https://knowledge.flowella.io/api-reference/templates/queue-template-send-job
/api-reference/openapi.json post /v1/templates/send
Accepts a bulk template send and processes it in the background. The request is validated at the door, queued durably, and returns `202 Accepted` immediately with a job id. Send an `Idempotency-Key` header to make retries safe: repeats of the same key within seven days return the original job id instead of sending the batch again. Without the header, Flowella derives a key from the request body, so an identical batch submitted twice in quick succession is not double-sent. Recipients are processed individually, so one invalid number does not block the rest of the batch.
# Outbound message analytics
Source: https://knowledge.flowella.io/api-reference/analytics/outbound-message-analytics
/api-reference/openapi.json get /v1/analytics
Aggregates outbound message counts and rates by status for a date range.
# Create or update contact
Source: https://knowledge.flowella.io/api-reference/contacts/create-or-update-contact
/api-reference/openapi.json post /v1/contacts
# List contacts
Source: https://knowledge.flowella.io/api-reference/contacts/list-contacts
/api-reference/openapi.json get /v1/contacts
# Set or clear per-channel WhatsApp opt-out
Source: https://knowledge.flowella.io/api-reference/contacts/set-or-clear-per-channel-whatsapp-opt-out
/api-reference/openapi.json post /v1/opt-outs
`action: set` creates or reactivates an opt-out for the given channel and phone. `action: clear` revokes it. Idempotent clears are safe.
# List conversations
Source: https://knowledge.flowella.io/api-reference/conversations/list-conversations
/api-reference/openapi.json get /v1/conversations
# Send WhatsApp text message
Source: https://knowledge.flowella.io/api-reference/messages/send-whatsapp-text-message
/api-reference/openapi.json post /v1/messages
# Ping (auth check)
Source: https://knowledge.flowella.io/api-reference/system/ping-auth-check
/api-reference/openapi.json get /v1/ping
Returns `ok` and the organization id for the resolved API key. Use to verify credentials.
# List WhatsApp templates
Source: https://knowledge.flowella.io/api-reference/templates/list-whatsapp-templates
/api-reference/openapi.json get /v1/templates
# Queue template send job
Source: https://knowledge.flowella.io/api-reference/templates/queue-template-send-job
/api-reference/openapi.json post /v1/templates/send
Accepts a bulk template send and processes it in the background. The request is validated at the door, queued durably, and returns `202 Accepted` immediately with a job id. Send an `Idempotency-Key` header to make retries safe: repeats of the same key within seven days return the original job id instead of sending the batch again. Without the header, Flowella derives a key from the request body, so an identical batch submitted twice in quick succession is not double-sent. Recipients are processed individually, so one invalid number does not block the rest of the batch.
# Outbound message analytics
Source: https://knowledge.flowella.io/api-reference/analytics/outbound-message-analytics
/api-reference/openapi.json get /v1/analytics
Aggregates outbound message counts and rates by status for a date range.
# Create or update contact
Source: https://knowledge.flowella.io/api-reference/contacts/create-or-update-contact
/api-reference/openapi.json post /v1/contacts
# List contacts
Source: https://knowledge.flowella.io/api-reference/contacts/list-contacts
/api-reference/openapi.json get /v1/contacts
# Set or clear per-channel WhatsApp opt-out
Source: https://knowledge.flowella.io/api-reference/contacts/set-or-clear-per-channel-whatsapp-opt-out
/api-reference/openapi.json post /v1/opt-outs
`action: set` creates or reactivates an opt-out for the given channel and phone. `action: clear` revokes it. Idempotent clears are safe.
# List conversations
Source: https://knowledge.flowella.io/api-reference/conversations/list-conversations
/api-reference/openapi.json get /v1/conversations
# Send WhatsApp text message
Source: https://knowledge.flowella.io/api-reference/messages/send-whatsapp-text-message
/api-reference/openapi.json post /v1/messages
# Ping (auth check)
Source: https://knowledge.flowella.io/api-reference/system/ping-auth-check
/api-reference/openapi.json get /v1/ping
Returns `ok` and the organization id for the resolved API key. Use to verify credentials.
# List WhatsApp templates
Source: https://knowledge.flowella.io/api-reference/templates/list-whatsapp-templates
/api-reference/openapi.json get /v1/templates
# Queue template send job
Source: https://knowledge.flowella.io/api-reference/templates/queue-template-send-job
/api-reference/openapi.json post /v1/templates/send
Accepts a bulk template send and processes it in the background. The request is validated at the door, queued durably, and returns `202 Accepted` immediately with a job id. Send an `Idempotency-Key` header to make retries safe: repeats of the same key within seven days return the original job id instead of sending the batch again. Without the header, Flowella derives a key from the request body, so an identical batch submitted twice in quick succession is not double-sent. Recipients are processed individually, so one invalid number does not block the rest of the batch.
# Outbound message analytics
Source: https://knowledge.flowella.io/api-reference/analytics/outbound-message-analytics
/api-reference/openapi.json get /v1/analytics
Aggregates outbound message counts and rates by status for a date range.
# Create or update contact
Source: https://knowledge.flowella.io/api-reference/contacts/create-or-update-contact
/api-reference/openapi.json post /v1/contacts
# List contacts
Source: https://knowledge.flowella.io/api-reference/contacts/list-contacts
/api-reference/openapi.json get /v1/contacts
# Set or clear per-channel WhatsApp opt-out
Source: https://knowledge.flowella.io/api-reference/contacts/set-or-clear-per-channel-whatsapp-opt-out
/api-reference/openapi.json post /v1/opt-outs
`action: set` creates or reactivates an opt-out for the given channel and phone. `action: clear` revokes it. Idempotent clears are safe.
# List conversations
Source: https://knowledge.flowella.io/api-reference/conversations/list-conversations
/api-reference/openapi.json get /v1/conversations
# Send WhatsApp text message
Source: https://knowledge.flowella.io/api-reference/messages/send-whatsapp-text-message
/api-reference/openapi.json post /v1/messages
# Ping (auth check)
Source: https://knowledge.flowella.io/api-reference/system/ping-auth-check
/api-reference/openapi.json get /v1/ping
Returns `ok` and the organization id for the resolved API key. Use to verify credentials.
# List WhatsApp templates
Source: https://knowledge.flowella.io/api-reference/templates/list-whatsapp-templates
/api-reference/openapi.json get /v1/templates
# Queue template send job
Source: https://knowledge.flowella.io/api-reference/templates/queue-template-send-job
/api-reference/openapi.json post /v1/templates/send
Accepts a bulk template send and processes it in the background. The request is validated at the door, queued durably, and returns `202 Accepted` immediately with a job id. Send an `Idempotency-Key` header to make retries safe: repeats of the same key within seven days return the original job id instead of sending the batch again. Without the header, Flowella derives a key from the request body, so an identical batch submitted twice in quick succession is not double-sent. Recipients are processed individually, so one invalid number does not block the rest of the batch.