Skip to main content

​
Overview

WhatsApp Business API allows your agent to communicate with customers via WhatsApp - the world’s most popular messaging app with 2+ billion users.

Business Messaging

Professional customer communication

Rich Media

Images, videos, documents, location

High Engagement

98% open rates

Global Reach

Available in 180+ countries

​
Prerequisites

Before connecting WhatsApp, you need:
Meta updates its developer dashboard and Business Suite UI frequently. The steps below describe what you need; for exact, up-to-date clicks, follow Meta’s official WhatsApp Cloud API — Get Started guide.
1

Meta Business Account

Create account at https://business.facebook.com
Meta Business signup
Screenshot: Meta Business account creation page
2

WhatsApp Business Account (WABA)

In Meta’s developer dashboard, create an app and select the WhatsApp use case. A WhatsApp Business Account is created for you, and you can open it under WhatsApp → API Setup.See Meta’s official guide: Create an app with the WhatsApp use case.
3

Phone Number

Add and verify a business phone number, or use the free test number Meta provides for development. See Meta’s Get Started guide for adding and verifying numbers.
4

Get Credentials

Collect the required information:
  • Phone Number ID
  • WhatsApp Business Account (WABA) ID
  • Access Token
All three appear on the WhatsApp → API Setup page of your app in the Meta developer dashboard. For production, generate a permanent token via a System User — see Meta’s Get Started guide.

​
Connection Method 1: CLI

​
Step-by-Step CLI Setup

1

Run Command

lua channels
2

Select Link New Channel

✅ Using agent: myAgent

? What would you like to do?
❯ 🔗 Link new channel
3

Select WhatsApp

? Select channel type:
❯ 📱 WhatsApp
  💬 Facebook Messenger
  📧 Email
  🔒 Slack (Private)
4

Enter Phone Number ID

? Enter phone number ID: 647834045087314
Find this in Meta Business Suite → WhatsApp → Phone Numbers
5

Enter WABA ID

? Enter WhatsApp Business Account ID (WABA ID): 1390592278829291
Find this in Meta Business Suite → WhatsApp → Settings
6

Enter Access Token

? Enter access token: ****
Generate in Meta Business Suite → System Users → Generate Token
7

Success

📡 Creating WhatsApp channel...

✅ WhatsApp channel created successfully!

📱 Phone Number: +15557986280
📊 Status: CONNECTED
🌍 Country: USA
🎯 Webhook URL: https://wa.heylua.ai/whatsapp/webhook/abc123

​
Configure Webhook in Meta

1

Copy Webhook URL

Copy the webhook URL from the CLI output.
2

Open WhatsApp Configuration

In your app’s developer dashboard, go to WhatsApp → Configuration.
3

Add Webhook

Click Edit, paste the webhook URL as the Callback URL, enter your Verify token, and save.
4

Subscribe to Events

Under Webhook fields, click Manage and subscribe to messages and message_status.
5

Verify

Meta sends a verification request to confirm the webhook. A green check confirms it’s connected.
Meta’s webhook setup UI changes periodically. For the current steps and field names, follow Meta’s official guide: Set up Webhooks for WhatsApp Cloud API.

​
Connection Method 2: Admin Dashboard

​
Step-by-Step Dashboard Setup

The dashboard uses Meta’s Embedded Signup, so you don’t enter credentials or configure webhooks by hand. Signing in with Facebook lets Meta provision (or connect) your WhatsApp Business Account, phone number, and webhook automatically. Use the CLI method instead if you already have credentials and prefer to enter them manually.
1

Open the dashboard

lua admin
Or visit https://admin.heylua.ai.
2

Open your agent

Click Agents in the main side navigation, then select your agent’s card.
3

Add a channel

Click the + (plus) icon to add a channel, then choose WhatsApp.
Add a channel
Screenshot: The agent’s add-channel (+) control and the WhatsApp option
4

Accept terms & connect

Tick the box to accept the Terms of Service and Privacy Policy, then click Connect.
5

Log in with Facebook

A Meta Embedded Signup popup opens. Log in with your Facebook details and continue the Facebook workflow — select or create your Business account, WhatsApp Business Account, and phone number. Meta handles verification and webhook setup for you.
This popup is Meta’s own UI and changes periodically. See Meta’s Embedded Signup overview if you get stuck.
6

Connection success

When signup completes, you’ll see a “WhatsApp channel connected” confirmation and WhatsApp appears in your connected channels.

​
Testing Your WhatsApp Channel

1

Send Test Message

From your phone, send WhatsApp message to your business number
You: Hi!
2

Agent Responds

Your agent should respond automatically
Agent: Hello! How can I help you today?
3

Monitor in Admin

View conversation in admin dashboard
WhatsApp conversation
Screenshot: Real-time conversation view

​
Message Status Events

When you send messages via WhatsApp (including template messages), Meta sends status updates back to Lua as messages progress through delivery. Lua captures these events and can forward them to your webhooks.

​
Status Lifecycle

A typical message goes through these statuses: 
sent → delivered → read
StatusMeaning
sentMessage accepted by WhatsApp servers
deliveredMessage delivered to recipient’s device
readRecipient opened and read the message
failedMessage could not be delivered (includes error details)
playedRecipient played a voice or video message

​
Tracking Delivery with Webhooks

To receive these events in your code, subscribe a webhook to the event types you need: 
lua webhooks subscribe --webhook-name my-tracker --event message.sent
lua webhooks subscribe --webhook-name my-tracker --event message.delivered
lua webhooks subscribe --webhook-name my-tracker --event message.read
lua webhooks subscribe --webhook-name my-tracker --event message.failed
Your webhook receives the full status payload including the message ID, recipient, timestamp, conversation context, and pricing information. See the Webhooks API Reference for the complete payload shape.
Status events are particularly useful when sending template messages via the Templates API. After sending a campaign, subscribe to message.delivered and message.read to measure engagement, or message.failed to catch delivery issues.

​
Prerequisites

For status events to flow through, make sure you’ve subscribed to messages and message_status in your Meta webhook configuration (see Configure Webhook in Meta above).

​
Status & Quality

​
Connection Status

  • 🟢 CONNECTED - Working normally
  • 🔴 DISCONNECTED - Needs reconnection
  • 🟡 PENDING - Setup in progress

​
Quality Rating

Meta assigns quality ratings based on user feedback:
  • 🟢 GREEN - High quality (good!)
  • 🟡 YELLOW - Medium quality (watch carefully)
  • 🔴 RED - Low quality (take action)
Low quality ratings can result in rate limiting or account restrictions. Monitor quality in admin dashboard.

​
Best Practices

  • Respond within 24 hours
  • Quick responses improve quality rating
  • Agent handles this automatically
  • Use templates for notifications
  • Required for messages after 24 hours
  • Set up in Meta Business Suite
  • Users must message you first
  • Cannot send unsolicited messages
  • Respect user privacy
lua admin
# Check quality rating regularly
# Address any user complaints promptly

​
Troubleshooting

Causes:
  • Token expired
  • WABA disabled
  • Phone number removed
Solution:
  1. Regenerate access token
  2. Update in admin dashboard
  3. Verify WABA is active
Check:
  • Quality rating (RED = issues)
  • Webhook configured correctly
  • Phone number status in Meta
  • Message templates approved
Actions:
  1. Review recent conversations
  2. Check user feedback in Meta
  3. Improve agent responses
  4. Address user complaints
  5. May need to adjust persona

​
Next Steps

Facebook Messenger

Connect another channel

Test Your Agent

Test agent behavior

Monitor Channels

View channel analytics

CLI Command Reference

Complete CLI guide