Send one-time passcodes over WhatsApp with the Flowella API

Your app creates a one-time passcode, sends it to the customer’s WhatsApp with the Flowella API, and checks the code the customer types in. The message uses an authentication template with a copy-code button. HubSpot’s role is optional: your app can log the outcome on the contact.

A HubSpot workflow can’t send passcodes. Flowella’s Send WhatsApp Template action can’t give an OTP or copy-code button a different value for each contact, and HubSpot shouldn’t hold the codes. Send codes from your app with the API instead.

At a glance

Item	Details
Trigger	A sign-in or sensitive action in your app
Flowella	`POST /v1/templates/send` with per-recipient `buttonParameters`
Template	One authentication template with a copy-code button (Authentication)
HubSpot	Optional. Your app logs the outcome on the contact, never the code
Timing	Code sent at once. Allow a resend no sooner than 15 seconds later

How it works

The diagram shows one sign-in attempt, from code request to sign-in or lockout.

Before you start

Create an API key. See API keys. This endpoint accepts API keys only, not OAuth access tokens.
Collect each customer’s WhatsApp number in international format, such as +447700900123, and their agreement to receive codes on WhatsApp. See Meta’s opt-in guidance.
Read the API introduction for authentication, errors and rate limits.

Create the template

Create the template in Meta’s WhatsApp Manager, with the Authentication category and a copy-code button. Only authentication templates may carry a one-time passcode, and they need a copy-code or one-tap button. Meta fixes the wording: “<code> is your verification code.” You can add a reminder not to share the code and an expiry line of 1 to 90 minutes. URLs, media and emojis aren’t allowed, and the code can be up to 15 characters. Once Meta approves the template, it appears in Flowella. See Meta’s template categorisation guidelines and copy code authentication templates. If you also message customers about a lockout, use a separate Utility template, such as

Hi {{1}}, we have paused sign-in to your account after several incorrect codes. Try again in 30 minutes or contact our support team.

An account security alert with no promotion fits Utility.

Send a code

Find the template and channel

Call GET /v1/templates?status=APPROVED. Note your template’s id and wabaId, and the whatsappChannelId of the number you send from. See Multi-channel if you have several numbers.

Create the code in your app

Generate a random code of up to 15 characters. Store a hash of it with a short expiry, and mark it single-use.

Send the request

Put the code in twice: once as the body parameter and once as the copy-code button’s value. Meta’s send format treats the copy-code button as a URL button, so use subType url, with index 0 for the first button.

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY" \
  -H "Idempotency-Key: otp-7f3c2a91" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "1234567890123456",
    "templateWabaId": "102290129340398",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [
      {
        "phone": "+447700900123",
        "bodyParameters": ["482913"],
        "buttonParameters": [
          { "index": 0, "subType": "url", "text": "482913" }
        ]
      }
    ]
  }'

A 202 response with "status": "accepted" means Flowella queued the send. It does not confirm delivery.

Check the code

When the customer types the code, compare it with the stored hash. Accept it once, and only before it expires.

Handle resends and lockout

Send a new code for each attempt and invalidate the old one. Wait at least 15 seconds before a resend: Flowella skips a second send of the same template to the same number within 15 seconds. Cap the attempts, then lock sign-in for a set period and offer support.

Log the outcome in HubSpot (optional)

Have your app update the HubSpot contact through HubSpot’s API, for example Last WhatsApp verification (Date and time picker) and Last verification result (Dropdown select: Passed, Failed, Locked). A HubSpot workflow can then create a task when the result is Locked. Never store codes in HubSpot.

Use a new Idempotency-Key for every code, such as your own verification ID. A repeat with the same key within 7 days returns the original id and sends nothing.

Test the integration

Send a code to your own WhatsApp number and check that the copy-code button copies it.
Enter a wrong code, then request a resend after the wait, and check that the old code no longer works.
Watch delivery with the message.delivered and message.failed webhook events. See Webhooks.

Troubleshooting

Symptom	Cause	Fix
`401` response	The key is missing or invalid, or you used an OAuth access token	Use a valid API key. See API keys.
`429` response	You exceeded the rate limit	Wait for the time in the `Retry-After` header, then retry.
A resend never arrives	It went within 15 seconds of the previous code, or reused an `Idempotency-Key`	Wait 15 seconds and use a new key.
No code arrives for one customer	The number opted out of messages from your WhatsApp number	The customer can send `START` to opt back in. See Opt-outs.
The send fails for long codes	The code is over 15 characters	Use a shorter code.

API introduction: authentication, idempotency, errors and rate limits.
Template reference: template categories and button types.
Webhooks: receive delivery events from Flowella.

Get Started

Essentials

Using the App

Settings

Meta & WhatsApp Setup

HubSpot Integration

Flows & Campaigns

API Reference

Troubleshooting

Changelog

Send one-time passcodes over WhatsApp with the Flowella API

At a glance

How it works

Before you start

Create the template

Send a code

Test the integration

Troubleshooting

​At a glance

​How it works

​Before you start

​Create the template

​Send a code

​Test the integration

​Troubleshooting

​Related

At a glance

How it works

Before you start

Create the template

Send a code

Test the integration

Troubleshooting

Related