How to connect WhatsApp to an AI Agent

Connect your Flametree AI agent to WhatsApp Business API to engage customers through one of the world's most widely used messaging platforms. This integration uses the official Meta API with a verified business phone number.

Prerequisites

• Meta Business Account - Register at business.facebook.com
• SIM card that meets these requirements:
  • Not registered with any WhatsApp account
  • Can receive SMS messages for OTP verification
• Admin access to your Flametree account

Setting Up WhatsApp Business API

Step 1: Create Meta Business Account and App

1. Register Business Account

   • Go to business.facebook.com and sign in
   • Complete business verification with company details

2. Create Developer App

   • Visit developers.facebook.com/apps
   • Click Create App and follow the setup wizard:
     • Use Cases: Select Other
     • App Type: Select Business
     • Enter app name, contact email, and select your business account

Step 2: Configure WhatsApp Integration

1. Add WhatsApp to Your App

   • In the App Dashboard, find the WhatsApp card
   • Click Set Up
   • Navigate to Quickstart → Start using API

2. Generate Access Token

   • Navigate to API Setup
   • Click Generate Access Token
   • Save this token - you'll need it for Flametree integration

Step 3: Register Phone Number

‼️ Critical: The phone number must NOT be registered with standard WhatsApp

1. Add Phone Number

   • Go to WhatsApp → API Setup
   • In the number dropdown, click Add phone number
   • Follow the wizard:
     • Enter phone number, country, and company name
     • Verify via SMS (you'll receive an OTP code)

2. Confirm Registration via API

   Execute this curl request to complete registration:

   curl 'https://graph.facebook.com/v21.0/<PHONE_ID>/register' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <TOKEN>' \
     -d '{
       "messaging_product": "whatsapp",
       "pin": "<PIN>"
     }'

   Parameter	Where to Find
   <PHONE_ID>	WhatsApp → API Setup
   <TOKEN>	WhatsApp → API Setup
   <PIN>	OTP code received via SMS

Step 4: Collect Integration Parameters

Save these values from Meta Developer Console:

Parameter	Location in Meta Console	Flametree Field
Access Token	WhatsApp → API Setup	WhatsApp Bot Token
App ID	App Settings → Basic	WhatsApp Application ID
App Secret	App Settings → Basic	WhatsApp Application Secret
Phone Number ID	WhatsApp → API Setup	WhatsApp Phone Number ID
Verify Token	WhatsApp → Configuration	WhatsApp Verify Token
Business Account ID	WhatsApp → API Setup	WhatsApp Business Account ID

Configuring Flametree Integration

Step 1: Create WhatsApp Integration

1. Navigate to Integrations
   • Go to Channels section in Flametree
   • Find WhatsApp card and click Add +

💡 Note: WhatsApp integration from Integrations section is outdated. Use Channels instead.

2. Fill Configuration

Field	Description	Required	Value Source
Name	Custom integration name	✅ Yes	Your choice
Description	Optional description	✅ Yes	Your choice
WhatsApp Bot Token	Access Token from Meta	✅ Yes	Meta Console
WhatsApp Application ID	App ID	✅ Yes	Meta Console
WhatsApp Application Secret	App Secret	✅ Yes	Meta Console
WhatsApp Phone Number ID	Phone Number ID	✅ Yes	Meta Console
WhatsApp Business Account ID	Business Account ID	✅ Yes	Meta Console
WhatsApp Verify Token	Custom verification string	✅ Yes	Your choice

3. Save Integration
   • Click Save to create the integration

Step 2: Connect to AI Agent

1. Open Agent Configuration

   • Navigate to your target AI agent's settings
   • Go to Channels section

2. Assign Channel

   • Select your WhatsApp integration from the list
   • Save the agent configuration

3. Restart Agent

   • Restart the agent for changes to take effect
   • This step is mandatory for the integration to work

❗️ Important: Always restart both the agent and channel after making changes.

Configuration Options

Environment Variables

Configure additional features through Set Environment Variables:

Variable	Default	Description	Scope
SHOW_VOICE_TRANSCRIPTION	true	Show transcription text for voice messages	Integrations & Channels
WA_SESSION_TIMEOUT	86400	Session timeout in seconds (default: 24 hours)	Integrations only

To configure:

1. Go to your agent's Set Environment Variables
2. Add the variable name and desired value
3. Save and restart the agent

Channel Environment Variables

Set these variables directly into the channel.

Variable	Description	Default
LOG_WEBHOOK_MESSAGES	Whether to log all requests that come to WhatsApp webhook	False

To configure:

1. Go to your channel's Set Environment Variables
2. Add the variable name and desired value, press Save
3. Restart the channel

Testing Your Integration

Quick Test Steps

1. Find Your Business Number

   • Use the phone number registered in Meta console
   • Send a message from any WhatsApp account to your business number

2. Send Test Message

   • Type any message to your business WhatsApp number
   • Verify the AI agent responds appropriately

3. Test Voice Messages (if enabled)

   • Send a voice message
   • Check if transcription appears (if SHOW_VOICE_TRANSCRIPTION is true)

Common Issues & Solutions

Phone number registration fails

Possible causes:

• Number already registered with WhatsApp
• SMS not received
• Incorrect API parameters

Solutions:

1. Verify number availability: Ensure the number is not in use with any WhatsApp account
2. Check SMS delivery: Verify SMS reception and try again
3. Validate API parameters: Ensure all parameters match Meta console values
4. Check SMS credits: Ensure sufficient SMS credits in your region

Webhook verification errors

Possible causes:

• Incorrect verify token
• Network connectivity issues
• Meta server delays

Solutions:

1. Match verify tokens: Double-check the WhatsApp Verify Token matches between Meta and Flametree
2. Check connectivity: Ensure Flametree servers can receive incoming webhooks
3. Wait and retry: Wait a few minutes and retry webhook setup
4. Review logs: Check integration logs for specific error messages

Messages not being delivered

Possible causes:

• Agent not restarted
• Invalid access token
• Rate limiting
• Phone number status issues

Solutions:

1. Restart agent: Restart your Flametree agent after integration setup
2. Verify token: Check if access token is still valid in Meta console
3. Check rate limits: Review Meta's developer dashboard for rate limiting
4. Phone status: Ensure phone number status is "Connected" in Meta console

FAQ

How to register a WhatsApp number in Meta?

To register a phone number in the WhatsApp Business API via Meta (Facebook), follow these steps:

1. Create a Business Account: Register at business.facebook.com
2. Create an App: Go to developers.facebook.com/apps and create a Business app
3. Add WhatsApp: In app dashboard, set up WhatsApp integration
4. Register Number: Use a SIM card not registered with WhatsApp, verify via SMS
5. Confirm via API: Execute the registration curl command with your OTP

Alternative: Use Bird.com as an official WhatsApp solution provider if you prefer not to go through Meta's direct verification.

Can I use my personal WhatsApp number?

No, you cannot use a number that's already registered with personal WhatsApp. You need a dedicated business number that hasn't been used with any WhatsApp account.

What's the difference between WhatsApp Business and WhatsApp Business API?

• WhatsApp Business: Mobile app for small businesses, limited automation
• WhatsApp Business API: Enterprise solution with full automation capabilities, webhooks, and integration support (what Flametree uses)

How much does WhatsApp Business API cost?

Meta charges based on conversations and message templates. Pricing varies by region and conversation type. Check Meta's pricing page for current rates.

Can I use the same WhatsApp number for multiple agents?

It depends on the channel mode:

• ✅ Yes — If you're using the channel in outbound mode only
• ❌ No — If any subscribed agent has already activated inbound mode

Why this limitation exists:

• Multiple agents listening for inbound messages on the same number would cause conflicts
• Messages might be processed by multiple agents simultaneously
• Response duplication and inconsistent behavior would occur

Best practice: Use dedicated WhatsApp numbers for each agent to ensure reliable message handling and avoid conflicts.

What message types are supported?

Flametree WhatsApp integration supports:

• ✅ Text messages
• ✅ Voice messages (with transcription)
• ✅ Images and videos
• ✅ Documents and files
• ❌ Location sharing
• ❌ Video calls
• ❌ Group management features

Do I need business verification to use WhatsApp API?

Yes, Meta requires business verification for WhatsApp Business API access. This includes:

• Valid business registration documents
• Verified business address
• Business website or social media presence
• Phone number verification

Timeline: Verification typically takes 1-3 business days but can take longer during peak periods.

Security Considerations

API Token Security

• Never share your access tokens publicly
• Rotate tokens regularly using Meta console
• Use environment variables in production deployments
• Monitor API usage for suspicious activity

Business Account Security

• Enable two-factor authentication on your Meta Business account
• Limit admin access to essential personnel only
• Regular audit of app permissions and access tokens
• Monitor webhook endpoints for unauthorized access

Privacy Compliance

• GDPR compliance: Ensure message handling meets data protection requirements
• Data retention: Configure appropriate message retention policies
• User consent: Implement proper opt-in mechanisms for marketing messages
• Encryption: All messages are encrypted by WhatsApp end-to-end

Related Resources

• Meta WhatsApp Business API Documentation
• WhatsApp Business API Pricing
• Agent Configuration Guide
• Knowledge Base Setup