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 and ensure it remains valid

Step 3: Register Phone Number

Critical

The phone number must not be registered with any WhatsApp account — business or personal — and must be able to receive SMS for verification

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

   note

   Make sure all parameters match the values from the Meta console. Incorrect values may cause registration to fail.

Step 4: Collect Integration Parameters

Save these values from Meta Developer Console:

Parameter	Location in Meta Console
App ID	App Settings > Basic
App Secret	App Settings > Basic
Access Token	WhatsApp > API Setup
Phone Number ID	WhatsApp > API Setup
Business Account ID	WhatsApp > API Setup

Configuring Flametree Integration

Step 1: Create WhatsApp Integration

1. Navigate to Settings

   • Go to Settings > Channels
   • Open WhatsApp
   • Select Add +

2. Fill Configuration

   Field	Description	Required	Value Source
   Name	Custom integration name	✅	Your choice
   Description	Integration purpose	❌	Your choice
   App ID	Default Meta app to subscribe webhook	✅	Meta Console
   App secret	Stored near the App ID in Meta console	✅	Meta Console
   Access token	Default app’s WhatsApp API token	✅	Meta Console
   Phone number ID	One or more phone IDs from the same Meta business	✅	Meta Console
   Business account ID	Meta business account ID	✅	Meta Console

   Field notes

   • Phone number ID: You can connect multiple numbers by entering comma-separated values. Example: 487008484500533, 487215647816419. Values must be provided in the same order across related fields.

   • When multiple numbers are configured, Flametree sends outbound messages through them in a fixed repeating sequence. After the first message, each recipient is handled by the same sender number.

3. Click Save to create the integration

4. Click Start in the upper-right corner to start the channel.

Step 2: Connect to AI Agent

1. Open Agent Configuration

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

2. Assign Channel

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

   You can use the same WhatsApp number for multiple agents only for outbound communication. For inbound messaging, every connected agent would reply to the same customer message, causing duplicate or conflicting answers — so use a dedicated number per agent.

3. Restart the agent: click Stop agent then Start agent to apply the changes.

If messages are not delivered, verify that the access token is valid and the phone number status is Connected in Meta console

Configuration Options

Configure additional features through Set Environment Variables:

Variable	Description	Default
SHOW_VOICE_TRANSCRIPTION	Show transcription text for voice messages	True
WA_REGISTRATION_DELAY	Delay (seconds) between WhatsApp webhook registration attempts	5.0
WA_REGISTRATION_COUNT	Number of WhatsApp webhook registration attempts	20
WEBHOOK_MESSAGES_LOGS_DIR	Directory path to store WhatsApp webhook logs (used if LOG_WEBHOOK_MESSAGES is True)	None
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

WhatsApp Message Handling

WhatsApp enforces a strict 24-hour customer service window. If a customer has not replied within the last 24 hours, standard free-form messaging is disabled for both the AI agent and human operators.

To reactivate a stale conversation or start a new outbound chat from the 360 View, operators must use pre-approved Meta templates:

1. In the chat interface, a Continue with template button will automatically appear if the 24-hour window has expired. (If starting a new chat from 360 View, click Start conversation +).
2. Select an approved template from the dropdown list.
3. If the template contains variables (for example, {{1}}, {{2}}), input fields will appear inline within the message preview. The system will attempt to auto-fill these based on saved contact data, but you can edit them manually.
4. Click Send template. The message will appear with a special template icon in the chat history, and the 24-hour window will reset once the customer replies.

info

Each 24-hour conversation session starts officially when the first business message is delivered

Testing the Integration

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)

4. Check supported message types

   • The integration supports text, voice messages with transcription, images, videos, documents, and files
   • Location sharing, video calls, and group management features are not supported

Security Considerations

• Protect access tokens and rotate them regularly in Meta console
• Enable two-factor authentication on your Meta Business account
• Limit admin access to required team members only
• Monitor API usage and webhook activity for suspicious behavior
• Ensure message handling, data retention, and user consent meet applicable privacy requirements

---

Related Resources

• Meta WhatsApp Business API Documentation
• WhatsApp Business API Pricing
• AI Agent Setup
• Adding Knowledge Sources