Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
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)

Set up in Meta Business Suite
WABA setup
Screenshot: WhatsApp Business Account setup in Meta
3

Phone Number

Add and verify business phone number
Phone verification
Screenshot: Phone number verification screen
4

Get Credentials

Collect required information:
  • Phone Number ID
  • WABA ID
  • Access Token
WhatsApp credentials
Screenshot: Where to find credentials in Meta Business Suite

​
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 CLI output
2

Open Meta Business Suite

Navigate to WhatsApp → Configuration
Meta webhook config
Screenshot: WhatsApp Configuration page in Meta
3

Add Webhook

Paste webhook URL and configure
Add webhook
Screenshot: Webhook URL input field
4

Subscribe to Events

Enable messages and message_status events
Webhook events
Screenshot: Event subscription checkboxes
5

Verify

Click verify button to confirm webhook
Webhook verified
Screenshot: Success message showing webhook verified

​
Connection Method 2: Admin Dashboard

​
Step-by-Step Dashboard Setup

1

Open Admin

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

Navigate to Channels

Click “Channels” in sidebar
Channels menu
Screenshot: Admin sidebar with Channels highlighted
3

Click Connect New Channel

Button in top right
Connect button
Screenshot: “Connect New Channel” button
4

Select WhatsApp

Channel types
Screenshot: Grid of channel type options
5

Enter Credentials

Fill in WhatsApp credentials form
WhatsApp form
Screenshot: Form with Phone ID, WABA ID, Token fields
6

Click Connect

Submit form
Connecting
Screenshot: Loading state while connecting
7

Connection Success

WhatsApp connected
Screenshot: Success message with phone number, status, webhook URL
8

Configure Webhook

Follow instructions to set webhook in Meta
Webhook guide
Screenshot: Step-by-step webhook configuration guide

​
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