WhatsApp Bot Deployment

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.

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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