Home Documentation WhatsApp Notifications via Meta Cloud API

WhatsApp Notifications via Meta Cloud API

BnBFlows sends automated WhatsApp messages to guests using the Meta WhatsApp Cloud API — the official, business-grade API from Meta. This guide covers account setup, required credentials, and the messages sent automatically by the platform.

WhatsApp notifications use the Meta WhatsApp Business Cloud API (formerly known as the WhatsApp Business API). You need a Meta Business account, a verified phone number and an approved WhatsApp Business App to use this feature. Setup is free — you pay Meta directly for messaging beyond the free-tier conversations.

Prerequisites

  • A Meta Business Manager account.
  • A WhatsApp Business Account (WABA) verified under your business.
  • A phone number registered as a WhatsApp Business number (cannot be an existing personal WhatsApp number).
  • An approved Meta App with whatsapp_business_messaging permission.

Setting up the Meta WhatsApp Cloud API

1
Create a Meta App

Go to developers.facebook.com/apps → Create App. Select Business as the app type. Link it to your Meta Business Account.

2
Add WhatsApp product

In your app dashboard, click Add a Product and select WhatsApp. Follow the prompts to link your WhatsApp Business Account and add a phone number.

3
Generate a system user access token

In Meta Business Manager → System Users, create a system user with Employee access. Add your app with whatsapp_business_messaging and whatsapp_business_management permissions. Generate a permanent (never-expiring) access token — copy and save this securely.

4
Get your Phone Number ID

In the WhatsApp section of your Meta App dashboard, go to API Setup. Your Phone Number ID is listed under the registered phone number — it looks like a long numeric string (e.g. 123456789012345).

5
Add credentials to BnBFlows

In your BnBFlows environment, set these two variables:

WHATSAPP_TOKEN=your_system_user_access_token
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id

Optionally, set WHATSAPP_API_VERSION to override the Graph API version (default: v19.0).

6
Verify the connection

Go to Settings → Integrations → WhatsApp in BnBFlows and click Send Test Message. Enter your personal WhatsApp number. If configured correctly, you will receive a test message within a few seconds.

Messages sent automatically by BnBFlows

Trigger Recipient Content
Booking confirmed Guest Booking reference, property name, check-in/out dates, room access code(s)
OTP login Staff / admin user One-time login code, valid for 10 minutes
Payment received Guest Payment amount, reference and booking confirmation
Invoice generated Guest Invoice number, amount due and due date
Check-in reminder Guest Property name, check-in date and booking reference

Message formatting

WhatsApp supports basic text formatting in messages:

  • *bold* — wrap text in asterisks for bold.
  • _italic_ — wrap text in underscores for italic.
  • `monospace` — backticks render in monospace (used for access codes).

BnBFlows uses these formats to make messages easy to read — access codes appear in monospace for clarity, property names are bolded, and critical warnings are in italic.

Phone number format

BnBFlows normalises phone numbers to the E.164 format required by the Meta API. The following input formats are automatically handled:

  • 0712345678 → 254712345678 (Kenyan local with leading 0)
  • 712345678 → 254712345678 (9-digit Kenyan)
  • +254712345678 → 254712345678 (strips the + prefix)
  • 254712345678 → 254712345678 (already correct)

For numbers outside Kenya, enter the full E.164 format (e.g. +233201234567 for Ghana) in the guest profile.

Meta pricing & free tier

Meta's WhatsApp Cloud API pricing is conversation-based:

  • Free tier — 1,000 free service conversations per month per WhatsApp Business Account.
  • Business-initiated conversations (e.g. booking confirmations) are charged at Meta's published rates per destination country.
  • User-initiated conversations (guest replies) are cheaper and counted differently.

View current rates at Meta's WhatsApp Pricing page.

WhatsApp Business templates may be required for certain message types (particularly marketing messages). Booking confirmations and access codes sent in response to a confirmed booking are typically classified as utility messages and may be sent without pre-approved templates. Check Meta's categorisation guidelines if you receive template errors.

Troubleshooting

Messages not sending / "not_configured" in logs

  • Verify WHATSAPP_TOKEN and WHATSAPP_PHONE_NUMBER_ID are set in your .env file.
  • Run php artisan config:clear after updating .env.
  • Check the Laravel log (storage/logs/laravel.log) for Meta WhatsApp error entries.

Error: "Access token has expired"

  • Ensure you generated a system user token, not a user access token. System user tokens do not expire.
  • Regenerate the token in Meta Business Manager → System Users.

Error: "The number is not a WhatsApp number"

  • The guest's phone number is not registered on WhatsApp. The message cannot be delivered. BnBFlows logs this error and continues — SMS via Africa's Talking is sent as a fallback.

Error: "Template not found"

  • This occurs when Meta requires a pre-approved template for the message type. Contact BnBFlows support for guidance on template registration.