---
title: "WhatsApp Bot Deployment"
description: "Deploy your Airia agents as WhatsApp bots to enable conversational AI via WhatsApp messaging."
---

Deploy your Airia agents as WhatsApp bots to bring AI-powered assistance directly to users through WhatsApp messaging. Users can interact with your agents via direct messages, creating seamless workflows within one of the world's most popular messaging platforms.

## Overview

The WhatsApp Bot interface allows you to deploy agents that users can interact with directly through WhatsApp. Once configured, your agent responds to messages sent to your WhatsApp Business number, providing AI-powered assistance to users on their mobile devices or WhatsApp desktop app.

<Note>
WhatsApp Bot deployment requires administrator access to your Airia account and a **verified** Meta Business account with WhatsApp Cloud API access. Business verification is required by Meta before you can use the WhatsApp Business API in production.
</Note>

## Prerequisites

Before deploying an agent to WhatsApp, you'll need:

- Administrator or Platform Admin access in Airia
- A **verified** Meta Business account (business.facebook.com)
- A Meta Developer account (developers.facebook.com)
- A WhatsApp Business account connected to Meta
- A verified phone number for WhatsApp Business
- A deployed agent ready to connect to WhatsApp

<Warning>
Meta Business Verification is required for production WhatsApp API access. You must complete business verification in Meta Business Manager before your WhatsApp bot can send messages to users. Verification requires official business documents (such as a Certificate of Incorporation, Business License, or Tax Registration) where the legal business name, address, and phone number match your Meta Business Manager information. The verification process typically takes 1-2 business days but may take longer.
</Warning>

## Creating a WhatsApp Cloud API App

The first step is to create a Meta App with WhatsApp Cloud API access and obtain the necessary credentials.

### Step 1: Create a Meta App

1. Navigate to [Meta for Developers](https://developers.facebook.com)
2. Log in with your Meta account
3. Click **My Apps** in the top navigation
4. Click **Create App**
5. Select **Other** as the use case, then click **Next**
6. Select **Business** as the app type, then click **Next**
7. Enter an **App name** (e.g., "Airia Bot")
8. Enter your **Contact email**
9. Select your **verified Business Account** (or create one if needed—note that new accounts must complete [Meta Business Verification](https://www.facebook.com/business/help/2058515294227817) before production use)
10. Click **Create App**

### Step 2: Add WhatsApp to Your App

1. In your app dashboard, scroll down to find **Add products to your app**
2. Find **WhatsApp** and click **Set up**
3. Select your **Meta Business Account** when prompted
4. Click **Continue**

### Step 3: Get Your WhatsApp Credentials

Navigate to **WhatsApp** > **API Setup** in the left sidebar to find your credentials:

**Phone Number ID:**
1. In the **API Setup** section, find the **From** dropdown
2. Select your WhatsApp Business phone number (or use the provided test number)
3. Copy the **Phone number ID** displayed below the dropdown

**Access Token:**
1. In the same **API Setup** section, find the **Temporary access token** area
2. For testing, click **Generate** to create a temporary token (expires in 24 hours)
3. For production, create a permanent **System User** access token (see next section)
4. Copy the access token

<Warning>
Temporary access tokens expire after 24 hours. For production deployments, you must create a permanent System User access token.
</Warning>

### Step 4: Create a Permanent Access Token (Production)

For production use, create a System User with a permanent access token:

1. Go to [Meta Business Suite](https://business.facebook.com)
2. Navigate to **Settings** > **Business Settings**
3. Under **Users**, click **System Users**
4. Click **Add** to create a new system user
5. Enter a name (e.g., "Airia Bot") and select **Admin** role
6. Click **Create System User**
7. Click on your new system user, then click **Add Assets**
8. Select **Apps**, find your WhatsApp app, and toggle **Full Control**
9. Click **Save Changes**
10. Click **Generate New Token**
11. Select your WhatsApp app from the dropdown
12. Under **Available Permissions**, select:
    - `whatsapp_business_messaging` - Send and receive messages
    - `whatsapp_business_management` - Manage WhatsApp Business account
13. Set **Token expiration** to **Never** for a permanent token
14. Click **Generate Token**
15. **Immediately copy the token** - you won't be able to see it again
16. Store this securely - you'll need it in Airia

<Tip>
System User tokens with "Never" expiration don't expire, but you should still rotate them periodically as a security best practice.
</Tip>

### Step 5: Get Your App Secret

The App Secret is used for webhook signature verification:

1. In your Meta App Dashboard, navigate to **App settings** > **Basic** in the left sidebar
2. Find the **App secret** field
3. Click **Show** to reveal the secret
4. Copy the App Secret
5. Store this securely - you'll need it in Airia

<Warning>
Never share your App Secret publicly or commit it to version control. This secret is used to verify that webhook requests are genuinely from Meta.
</Warning>

## Configuring Your WhatsApp Bot Deployment in Airia

Now you'll create the WhatsApp Bot deployment in Airia and connect it to your agent:

### Step 1: Create a WhatsApp Bot Interface

1. Navigate to your agent in the Airia platform
2. Click on the **Interfaces** section in Agent Settings
3. Click **Add Interface** or **New Deployment**
4. Select **WhatsApp Bot** as the interface type

### Step 2: Add Your WhatsApp Cloud API Credential

1. In the credential dropdown, select **Create new credential** or choose an existing WhatsApp Cloud API credential
2. If adding a new credential, provide:
   - **Credential Name**: A descriptive name (e.g., "Production WhatsApp Bot")
   - **Access Token**: Your permanent System User access token (or temporary token for testing)
   - **Phone Number ID**: The Phone Number ID from your WhatsApp API Setup
   - **App Secret**: The App Secret from your Meta App Settings
3. Click **Create Credential**
4. This connects your deployment to your WhatsApp Business account

<Note>
WhatsApp Cloud API credentials can be reused across multiple WhatsApp bot deployments in your organization.
</Note>

### Step 3: Configure Execution Settings

Choose how the agent should execute when triggered from WhatsApp:

**Anonymous**
- Execute without user context
- No user mapping required
- All messages are processed with the same permissions
- Best for: Public bots where user identity isn't important

**Agent Creator**
- Execute as the user who created this agent
- Uses agent creator's permissions for all executions
- No additional configuration needed
- Best for: Bots with consistent permission requirements

**Airia User** (Recommended)
- Map WhatsApp users to existing Airia users
- Each user's execution uses their own Airia permissions
- Users are matched by phone number
- Best for: Enterprise deployments with role-based access control

When selecting "Airia User", you can optionally enable **"Automatically create Airia users"**:
- When enabled, new Airia accounts are automatically created for WhatsApp users who don't have an Airia account
- Users are created with the "End User" role by default
- The WhatsApp phone number is stored in the user's profile for matching

<Tip>
Select "Airia User" with automatic user creation for deployments where you want seamless access without manual account provisioning.
</Tip>

### Step 4: Copy the Webhook URL and Verify Token

After configuring the execution settings:

1. Click **Create Deployment**
2. Airia generates a **Webhook URL** and a **Verify Token**
3. Click the **Copy** button next to the Webhook URL to copy it
4. Click the **eye icon** next to the Verify Token to reveal it, then copy it
5. Keep both values handy - you'll need them to configure the webhook in Meta
6. The deployment is now created and ready for webhook configuration

<Note>
The Webhook URL and Verify Token are unique to this deployment. The Verify Token is auto-generated by Airia and is used by Meta to verify the webhook connection.
</Note>

## Configuring the Webhook in Meta

Return to your Meta App configuration to set up the webhook connection:

### Step 1: Configure Webhook URL

1. Go back to [Meta for Developers](https://developers.facebook.com) and select your app
2. In the left sidebar, navigate to **WhatsApp** > **Configuration**
3. Find the **Webhook** section
4. Click **Edit** (or **Configure** if setting up for the first time)
5. In the **Callback URL** field, paste the **Webhook URL** you copied from Airia
6. In the **Verify token** field, paste the **Verify Token** you copied from Airia
7. Click **Verify and save**

<Warning>
Make sure your Airia deployment is created before attempting to verify the webhook in Meta, otherwise verification will fail. The Verify Token is auto-generated by Airia - do not use your App Secret here.
</Warning>

### Step 2: Subscribe to Webhook Events

After the webhook is verified:

1. In the **Webhook fields** section, find the **messages** field
2. Click **Subscribe** next to the messages field
3. This enables your bot to receive incoming WhatsApp messages

<Note>
You only need to subscribe to the `messages` webhook field. Airia handles all message types automatically.
</Note>

### Step 3: Verify Phone Number (Production)

For production deployments, you need a verified business phone number:

1. In Meta Business Suite, navigate to **WhatsApp Manager**
2. Go to **Phone Numbers**
3. Click **Add phone number** if you haven't already
4. Follow the verification process (SMS or voice call verification)
5. Once verified, ensure this phone number is selected in your Meta App's WhatsApp API Setup

<Tip>
For testing, you can use the test phone number provided by Meta. However, test numbers can only send messages to numbers you've added to your allowed list.
</Tip>

## Testing Your WhatsApp Bot

Your WhatsApp bot is now fully configured and ready to use:

1. Open WhatsApp on your phone or desktop
2. Send a message to your WhatsApp Business number
3. The message should be received by your Airia agent
4. You should receive a response from the agent through WhatsApp

<Tip>
If using a test phone number, make sure your personal number is added to the "To" list in the Meta App's API Setup page before testing.
</Tip>

## User Mapping (For "Airia User" Mode)

If you selected "Airia User" as your execution configuration, Airia maps WhatsApp users to Airia users based on phone numbers.

### How Automatic Mapping Works

Airia automatically matches WhatsApp users to Airia users when:
- The user's WhatsApp phone number matches a phone number stored in an Airia user profile
- Phone numbers are matched in E.164 format (e.g., +1234567890)

When a user sends a message to the bot:
1. Airia receives the user's WhatsApp phone number from the webhook payload
2. Searches for an Airia user with a matching phone number
3. If found, executes the agent with that Airia user's permissions and context
4. If not found and auto-provisioning is enabled, creates a new Airia user with "End User" role

### Setting Up User Phone Numbers

To enable user mapping for existing Airia users:

1. Navigate to **Settings** > **User Management** in Airia
2. Select a user to edit
3. Add their phone number in E.164 format (e.g., +1234567890)
4. Save the user profile

<Warning>
If a WhatsApp user cannot be matched to an Airia user and auto-provisioning is disabled, they will receive a message indicating they don't have access. Enable "Automatically create Airia users" to allow seamless access.
</Warning>

## Using Your WhatsApp Bot

Once deployed, users can interact with your agent through WhatsApp direct messages:

### Direct Messages

Users can send direct messages to your WhatsApp Business number:

1. Add the WhatsApp Business number to their contacts (optional but recommended)
2. Open a chat with the number in WhatsApp
3. Type a message and send
4. The bot will respond directly in the conversation
5. The conversation maintains context across multiple messages

### Supported Message Types

WhatsApp bots support:
- **Text messages**: Standard text conversations
- **Media messages**: Images and documents can be sent to the bot
- **Long responses**: Responses over 4096 characters are automatically split into multiple messages

<Note>
WhatsApp has a 4096 character limit per message. Airia automatically chunks longer responses while preserving markdown formatting where possible.
</Note>

## Best Practices

### Security

- **Token Protection**: Keep your Access Token secure and rotate it periodically
- **App Secret Protection**: Never expose your App Secret publicly - it's used for webhook verification
- **Webhook URL Protection**: Keep your webhook URL private
- **Access Control**: Configure your agent's policies to control what data the bot can access
- **Audit Logs**: Regularly review bot activity in Airia's monitoring feeds
- **Execution Context**: Choose the appropriate execution configuration based on your security requirements

### User Experience

- **Clear Bot Identity**: Use a recognizable WhatsApp Business profile with a clear name and profile picture
- **Response Time**: Ensure your agent is optimized for quick responses
- **Error Handling**: Configure graceful error messages when the bot can't fulfill requests
- **Context Awareness**: Enable chat history in your agent's configuration to maintain conversation context
- **User Guidance**: Include a welcome message or instructions in your bot's first response

### Agent Configuration

- **Clear Instructions**: Provide clear system prompts that define the bot's role and capabilities
- **Tool Access**: Ensure your agent has access to necessary tools and data sources
- **Rate Limiting**: Configure appropriate usage limits to prevent abuse
- **Monitoring**: Set up alerts for errors or unusual activity
- **Message Length**: Keep responses concise - long messages may be split across multiple WhatsApp messages

## Use Cases

### Customer Support Bot

Deploy an agent that handles customer inquiries:
- Product information and FAQs
- Order status lookups
- Return and refund requests
- Appointment scheduling
- Escalation to human agents

### Appointment Booking Bot

Create a bot that manages appointments:
- Check availability
- Book appointments
- Send reminders
- Reschedule or cancel
- Collect required information

### Lead Qualification Bot

Deploy a bot that qualifies incoming leads:
- Capture contact information
- Ask qualifying questions
- Route to appropriate sales team
- Schedule follow-up calls
- Send relevant materials

### Internal Assistant Bot

Build an agent for internal team use:
- Quick information lookups
- Task reminders
- Document retrieval
- Process guidance
- IT support requests

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bot is not responding to messages">
    Check the following:
    - Verify the WhatsApp Cloud API credential in Airia has the correct Access Token, Phone Number ID, and App Secret
    - Ensure the webhook URL is correctly configured in your Meta App's WhatsApp Configuration
    - Confirm the webhook was successfully verified (green checkmark in Meta)
    - Check that you've subscribed to the `messages` webhook field
    - Check that the agent deployment is active in Airia
    - Review error logs in Airia's monitoring feeds (Conversation Feed)
    - Verify your WhatsApp Business number is active and verified
  </Accordion>

  <Accordion title="Meta webhook verification failed">
    This indicates the webhook couldn't be verified:
    - Ensure your Airia deployment is created and active before attempting verification
    - Copy both the Webhook URL and Verify Token from Airia (don't manually type them)
    - Use the **Verify Token** from Airia, not your App Secret
    - Click the eye icon in Airia to reveal the Verify Token before copying
    - Check that there are no extra spaces or characters when pasting
    - Wait a moment after creating the deployment before verifying in Meta
    - If the issue persists, delete and recreate the deployment in Airia
  </Accordion>

  <Accordion title="Access token expired or invalid">
    This typically occurs with temporary tokens:
    - Temporary tokens expire after 24 hours
    - For production, create a permanent System User access token
    - Navigate to Meta Business Settings > System Users
    - Generate a new token with "Never" expiration
    - Update the credential in Airia with the new token
  </Accordion>

  <Accordion title="Bot responds to some users but not others">
    This may be a permissions or user mapping issue:
    - If using "Airia User" execution mode, verify affected users have an Airia account with a matching phone number
    - Phone numbers must be in E.164 format (e.g., +1234567890) to match
    - If auto-provisioning is disabled, users must have pre-existing Airia accounts
    - Review your agent's policies in Airia for user-level restrictions
    - If using a test phone number, verify the recipient is in the allowed list
  </Accordion>

  <Accordion title="Messages from test number don't arrive">
    When using Meta's test phone number:
    - Test numbers can only message phone numbers in the "To" allowed list
    - Go to WhatsApp > API Setup in your Meta App
    - Add recipient phone numbers to the "To" field
    - Numbers must be in E.164 format with country code
    - You can only add up to 5 test recipients
  </Accordion>

  <Accordion title="Bot responses are slow or timing out">
    Performance optimization steps:
    - Review your agent's configuration for inefficient steps
    - Check if external tool integrations are responding slowly
    - Monitor token consumption and rate limits
    - Consider simplifying complex agent workflows
    - Check Airia platform status for any service issues
    - WhatsApp has a 20-second timeout for webhook responses
  </Accordion>

  <Accordion title="Long messages are being cut off">
    WhatsApp has a 4096 character limit per message:
    - Airia automatically splits long responses into multiple messages
    - If splitting causes formatting issues, consider updating your agent's system prompt to request more concise responses
    - Complex markdown (tables, nested lists) may not render properly when split
  </Accordion>

  <Accordion title="Can I deploy the same agent to multiple WhatsApp numbers?">
    Yes, each phone number requires its own deployment:
    - Create a separate WhatsApp Bot deployment for each phone number
    - Each deployment needs its own credential with the corresponding Phone Number ID
    - You can use the same Access Token if the phone numbers are in the same Meta Business account
    - Each deployment operates independently with its own webhook URL
  </Accordion>

  <Accordion title="How do I update my WhatsApp Business profile?">
    WhatsApp Business profile is managed in Meta:
    - Go to [WhatsApp Manager](https://business.facebook.com/wa/manage/home/) in Meta Business Suite
    - Navigate to **Account tools** > **Phone numbers**
    - Select your phone number
    - Update **Business profile** settings including name, description, and profile picture
    - Changes may take a few minutes to propagate
  </Accordion>

  <Accordion title="The bot can't maintain conversation context">
    Enable chat history in your agent:
    - Edit your agent in Airia's Agent Studio
    - Navigate to AI steps in your agent flow
    - Enable **"Include the chat history"** option for all LLM steps
    - This allows the agent to reference previous messages in the conversation
    - Save your agent configuration
  </Accordion>

  <Accordion title="Webhook signature verification failed">
    This indicates a mismatch between secrets:
    - Verify your App Secret is correctly entered in Airia's credential
    - The App Secret must match exactly (no extra spaces)
    - Regenerate the webhook URL if you've changed the App Secret
    - Check that you're using the correct Meta App's secret
  </Accordion>

  <Accordion title="Meta Business Verification not complete">
    WhatsApp Business API requires a verified Meta Business account for production use:
    - Go to [Meta Business Settings](https://business.facebook.com/settings/security) > **Security Center**
    - Check your **Business verification** status
    - If not verified, click **Start verification** and follow the prompts
    - You'll need to provide official business documents (Certificate of Incorporation, Business License, Tax Registration, etc.)
    - Documents must show your legal business name, address, and phone number matching your Meta Business Manager information
    - Verification typically takes 1-2 business days but may take up to several weeks
    - Until verification is complete, you can only use test phone numbers with limited recipients
  </Accordion>
</AccordionGroup>

## Managing Your WhatsApp Bot

### Monitoring Activity

Track your bot's usage and performance:

1. Navigate to **Feeds** in Airia
2. Select **Conversation Feed** to view bot interactions
3. Review **Token Consumption** for usage patterns
4. Check **Agent Executions** for performance metrics
5. Monitor user engagement and response times

### Updating Configuration

To modify your bot's behavior:

1. Edit the agent in Airia's Agent Studio
2. Make your changes to prompts, tools, or flow logic
3. Save the agent
4. Changes take effect immediately for new conversations

To modify deployment settings:

1. Navigate to the **Interfaces** section in Agent Settings
2. Click on your WhatsApp Bot deployment to edit
3. Update execution configuration or credential
4. Click **Save Changes**
5. The deployment will use the new settings immediately

### Updating Credentials

If your credentials need to be updated:

1. In Airia, navigate to **Settings** > **Credentials**
2. Find your WhatsApp Cloud API credential
3. Update the Access Token, Phone Number ID, or App Secret as needed
4. Save the credential
5. Your deployments will automatically use the updated credential

### Regenerating Webhook URL and Verify Token

If your webhook URL or Verify Token is compromised or you need new ones:

1. Navigate to your WhatsApp Bot deployment in Airia
2. Click **Delete** to remove the existing deployment
3. Create a new WhatsApp Bot deployment (you can reuse the same credential)
4. Copy the new Webhook URL and Verify Token
5. Update the Callback URL and Verify token in your Meta App's WhatsApp Configuration
6. Click **Verify and save** in Meta to verify the new URL

### Removing the Bot

To deactivate a WhatsApp bot deployment:

1. In Airia, navigate to your agent's Interfaces section
2. Click on the WhatsApp Bot deployment
3. Click **Delete** at the bottom of the configuration screen
4. Confirm the deletion
5. Optionally, remove the webhook configuration in Meta:
   - Go to your Meta App > WhatsApp > Configuration
   - Clear the Callback URL and verify token
   - Unsubscribe from webhook fields

## Security Considerations

### Data Privacy

- **Message Content**: All messages sent to your bot are processed by your Airia agent
- **Data Retention**: Configure data retention settings in Airia's admin settings
- **Compliance**: Ensure your deployment meets your organization's compliance requirements
- **User Consent**: Communicate to users how their messages will be processed
- **Phone Number Privacy**: User phone numbers are stored for user mapping when using "Airia User" mode

### Access Control

- **Phone Number Verification**: Only messages from valid WhatsApp accounts are processed
- **User Authentication**: WhatsApp handles user authentication through phone verification
- **Policy Enforcement**: Use Airia's policy features to filter sensitive content
- **Role-Based Access**: Configure agent-level permissions for different user groups
- **Credential Management**: Regularly rotate your Access Token as a security best practice

### Incident Response

Prepare for security incidents:

- **Quick Deactivation**: Know how to quickly delete the deployment in Airia to stop the bot
- **Webhook Security**: If webhook URL or Verify Token is exposed, regenerate them immediately by recreating the deployment
- **Credential Rotation**: If credentials are compromised, generate a new Access Token and update in Airia
- **Audit Logging**: Monitor bot activity in Airia's Conversation Feed and Agent Executions
- **Incident Procedures**: Document steps to disable the bot quickly if needed
- **User Reporting**: Provide a way for users to report issues with the bot

## Support

For additional help with WhatsApp Bot deployment:

- Review [Meta's WhatsApp Cloud API documentation](https://developers.facebook.com/docs/whatsapp/cloud-api)
- Check [WhatsApp Business Platform documentation](https://developers.facebook.com/docs/whatsapp)
- Check Airia's monitoring feeds for error details
- Contact your Airia account administrator
- Reach out to Airia support for platform-specific issues
