How to Set Up an AI WhatsApp Assistant

WhatsApp is the world's most popular messaging platform with over two billion users. Connecting your OpenClaw AI agent to WhatsApp allows you to reach customers, clients, and users on the platform they already use daily. Whether for customer support, personal assistance, or business automation, a WhatsApp AI assistant meets people where they are.

In this guide, you will set up a WhatsApp Business account, configure the WhatsApp Cloud API, connect it to your EZClaws agent, and test the integration. The result is an AI assistant that responds to WhatsApp messages automatically with the full power of OpenClaw.

Prerequisites

Before starting, gather the following:

• A running OpenClaw agent on EZClaws — Deploy one using our deployment guide.
• A Meta (Facebook) Business account — Create one at business.facebook.com if you do not have one.
• A phone number for WhatsApp Business — This must be a number not already registered with personal WhatsApp. A new SIM card or virtual number works.
• An active EZClaws subscription — WhatsApp messaging can generate significant usage. See plans at /pricing.

Step 1: Set Up WhatsApp Business API Access

Navigate to the Meta for Developers portal and create a new app or use an existing one.

Create a Meta App

1. Click Create App on the developer portal.
2. Select Business as the app type.
3. Fill in the app name and contact email.
4. Select your Meta Business account.
5. Click Create App.

Add WhatsApp Product

On your app's dashboard:

1. Find WhatsApp in the product list and click Set Up.
2. Follow the prompts to link your Meta Business account.
3. Meta provides a test phone number and a temporary access token for development.

Get Permanent Access Token

The test token expires after 24 hours. For production use, generate a permanent token:

1. In the Meta Developer Portal, go to System Users under your Business Settings.
2. Create a System User with Admin role.
3. Generate a token with whatsapp_business_messaging and whatsapp_business_management permissions.

# Your permanent access token will look like:
EAAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Register Your Phone Number

To use your own phone number instead of the test number:

1. Go to WhatsApp > Getting Started in your app settings.
2. Click Add phone number.
3. Enter the phone number and verify it via SMS or voice call.
4. The number must not be registered with WhatsApp personal or WhatsApp Business app.

Step 2: Configure the Webhook

WhatsApp sends incoming messages to your agent via a webhook. You need to configure this webhook URL in the Meta Developer Portal.

Set Up Webhook in Meta

1. Go to your app's WhatsApp > Configuration page.
2. Click Edit next to the Webhook field.
3. Enter your agent's WhatsApp webhook URL:

Callback URL: https://your-agent-domain.up.railway.app/whatsapp/webhook
Verify Token: your-custom-verify-token

The verify token is a secret string you choose. It is used to verify that webhook requests are coming from Meta. Enter the same token in both the Meta portal and your EZClaws skill configuration.

4. Click Verify and Save. Meta will send a verification request to your agent's endpoint.

Subscribe to Webhook Events

After verification, subscribe to the messages webhook field. This tells Meta to send incoming WhatsApp messages to your agent.

Subscribed fields:
- messages  — Incoming messages from users

Step 3: Install the WhatsApp Skill on EZClaws

Navigate to the EZClaws skills marketplace at /app/marketplace and find the WhatsApp integration skill.

Install it on your agent and configure the following:

Required Configuration

WhatsApp Access Token: EAAxxxxxxxxxxxxxxxxxxxxxxxx (from Step 1)
Phone Number ID: 123456789012345 (from your WhatsApp Business settings)
Webhook Verify Token: your-custom-verify-token (must match Meta configuration)
Business Account ID: 987654321098765 (from your Meta Business settings)

Optional Configuration

Default Language: en
Response Timeout: 30 seconds
Media Processing: enabled
Read Receipts: enabled
Typing Indicator: enabled

Save the configuration. Your agent will begin listening for incoming WhatsApp messages.

Step 4: Configure Message Templates

WhatsApp Business requires pre-approved message templates for proactive messaging (messages sent outside the 24-hour response window).

Create Templates in Meta

1. Go to WhatsApp > Message Templates in the Meta Business Manager.
2. Click Create Template.
3. Choose a category (Marketing, Utility, or Authentication).
4. Write your template with variable placeholders.

Example templates:

Template: welcome_message
Category: Utility
Body: "Hi {{1}}, thanks for reaching out! I'm an AI assistant
powered by EZClaws. How can I help you today?"

Template: follow_up
Category: Utility
Body: "Hi {{1}}, just checking in regarding your question about {{2}}.
Is there anything else I can help with?"

Template: support_resolution
Category: Utility
Body: "Hi {{1}}, your issue regarding {{2}} has been resolved.
If you need further assistance, just reply to this message."

Submit templates for approval. Meta typically reviews templates within 24 hours.

Configure Template Usage

In your agent's system prompt, include instructions about when to use templates:

WHATSAPP TEMPLATE RULES:
- When a user has not messaged in more than 24 hours, use the "follow_up"
  template to re-engage
- For new users messaging for the first time, acknowledge with the
  "welcome_message" template
- After resolving an issue, send the "support_resolution" template

Step 5: Configure Agent Behavior for WhatsApp

WhatsApp has unique characteristics that your agent should account for:

System Prompt Template

You are an AI assistant available on WhatsApp for [Business Name].

WHATSAPP-SPECIFIC GUIDELINES:
- Keep messages concise — WhatsApp users expect brief, chat-style responses
- Use short paragraphs and line breaks for readability on mobile
- Use WhatsApp formatting: *bold*, _italic_, ~strikethrough~, ```monospace```
- For long responses, break into multiple messages
- Respond promptly — users expect quick replies on WhatsApp
- Use emoji sparingly to feel natural and friendly

MEDIA HANDLING:
- When a user sends an image, analyze it and respond appropriately
- When a user sends a document, read and summarize if relevant
- When a user sends a voice note, transcribe and respond to the content

CONVERSATION MANAGEMENT:
- Greet new users and explain your capabilities
- For complex issues, ask clarifying questions one at a time
- Offer to connect users with a human agent for sensitive matters
- Track the 24-hour messaging window and use templates when needed

PRIVACY:
- Do not ask for sensitive information (passwords, credit card numbers)
- Inform users that conversations are processed by AI
- Respect opt-out requests immediately

Step 6: Test the Integration

Test your WhatsApp assistant thoroughly before making it available to users:

Test with the Test Number

Meta provides a test phone number during setup. Use it for initial testing:

1. Add the test number to your WhatsApp contacts.
2. Send a message to the test number.
3. Verify the agent responds correctly.

Test with Your Production Number

After verifying with the test number, switch to your registered phone number:

1. Send a message from your personal WhatsApp to the business number.
2. Verify the response arrives and is correctly formatted.

Test Scenarios

Test 1: Text message
Send: "Hi, what can you help me with?"
Expected: Welcome message with capabilities

Test 2: Image message
Send: [photo of a product]
Expected: Agent describes or analyzes the image

Test 3: Document message
Send: [PDF document]
Expected: Agent reads and summarizes the document

Test 4: Multiple messages
Send several messages in quick succession
Expected: Agent processes and responds to each

Test 5: Long conversation
Have a multi-message conversation spanning several topics
Expected: Agent maintains context throughout

Test 6: Template message test
Wait 24+ hours, then try to send a follow-up
Expected: Agent uses an approved template

Step 7: Go Live

Once testing is complete, prepare for production use:

Display Name Verification

Apply for a display name for your WhatsApp Business number:

1. Go to WhatsApp > Phone Numbers in Meta Business Manager.
2. Request a display name that represents your business.
3. Meta will verify the name against your business information.

Quality Rating

Meta monitors the quality of your WhatsApp messages based on user feedback. Maintain a high quality rating by:

• Responding quickly and accurately.
• Not sending spammy or irrelevant messages.
• Respecting user opt-out requests.
• Using templates appropriately.

Promote Your WhatsApp Assistant

Share your WhatsApp number with customers through:

• Your website with a "Chat on WhatsApp" button.
• Email signatures.
• Social media profiles.
• Business cards and marketing materials.
• QR codes linking to https://wa.me/your_number.

<!-- WhatsApp chat link for your website -->
<a href="https://wa.me/1234567890?text=Hi,%20I'd%20like%20to%20know%20more">
  Chat with us on WhatsApp
</a>

Troubleshooting

Messages are not reaching the agent

1. Verify webhook configuration — Check that the webhook URL is correct in Meta's portal.
2. Check agent status — Ensure the agent is "Running" on the EZClaws dashboard.
3. Verify access token — Make sure the permanent access token has not expired.
4. Check webhook subscriptions — Verify the messages field is subscribed.

Agent responds but messages are not delivered to WhatsApp

1. Check access token permissions — Ensure whatsapp_business_messaging permission is granted.
2. Verify phone number ID — Ensure the correct Phone Number ID is configured.
3. Check Meta app status — Your Meta app must be in "Live" mode for production use.
4. Review rate limits — Meta imposes message rate limits based on your quality rating.

24-hour window issues

1. Use templates — For messages outside the 24-hour window, use approved templates.
2. Track windows — Have the agent track when each user's 24-hour window opens and closes.
3. Prompt engagement — Encourage users to message again if you need to continue the conversation.

Poor response quality

1. Refine system prompt — Add WhatsApp-specific formatting and behavior instructions.
2. Upgrade model — Use GPT-4o or Claude for better conversational quality.
3. Add context — Provide the agent with information about your products, services, and common questions.
4. Enable memory — Persistent memory improves conversation quality over time. See memory guide.

Compliance and Best Practices

WhatsApp Commerce Policy

Ensure your AI assistant complies with WhatsApp's Commerce and Business policies:

• Do not use WhatsApp for sending unsolicited promotional messages.
• Obtain user consent before adding them to automated messaging.
• Provide a clear opt-out mechanism.
• Do not impersonate other businesses or individuals.

Data Privacy

• Inform users that messages are processed by AI.
• Comply with GDPR and other applicable privacy regulations.
• Do not store sensitive personal data unnecessarily.
• Review your privacy policy at /privacy and terms at /terms.

User Experience

• Respond within seconds — WhatsApp users have high expectations for response time.
• Use a conversational, friendly tone appropriate for messaging.
• Provide clear options when the user needs to make a choice.
• Always offer a way to reach a human agent.

Summary

Setting up an AI WhatsApp assistant with EZClaws connects your agent to the world's largest messaging platform. The process involves creating a Meta Business account, configuring the WhatsApp Cloud API, installing the WhatsApp skill, and testing thoroughly.

A WhatsApp AI assistant is ideal for customer support, appointment booking, order tracking, FAQ handling, and general assistance. With over two billion WhatsApp users, it is a powerful channel for reaching customers where they already are.

For other messaging integrations, check out our guides for Telegram, Discord, and Slack. Explore more use cases on our use cases page and stay updated with our blog.