WhatsApp Bot Deployment

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.

WhatsApp Bot deployment requires administrator access to your Airia account and a Meta Business account with WhatsApp Cloud API access.

Prerequisites

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

• Administrator or Platform Admin access in Airia
• A 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

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
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 Business Account (or create one if needed)
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

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

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
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

System User tokens with “Never” expiration don’t expire, but you should still rotate them periodically as a security best practice.

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

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.

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

WhatsApp Cloud API credentials can be reused across multiple WhatsApp bot deployments in your organization.

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

Select “Airia User” with automatic user creation for deployments where you want seamless access without manual account provisioning.

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

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.

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 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

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.

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

You only need to subscribe to the messages webhook field. Airia handles all message types automatically.

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

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.

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

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.

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., [phone])

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., [phone])
4. Save the user profile

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.

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

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

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

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

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

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

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., [phone]) 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

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

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

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

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

How do I update my WhatsApp Business profile?

WhatsApp Business profile is managed in Meta:

• Go to WhatsApp Manager 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

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

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

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
• Check WhatsApp Business Platform documentation
• Check Airia’s monitoring feeds for error details
• Contact your Airia account administrator
• Reach out to Airia support for platform-specific issues