# WhatsApp Integration

Put your AVCodex agent in the field tech's pocket. Connect AVCodex to WhatsApp so installers, programmers, and end-clients can ask questions from the rack room, the boardroom, or the truck.

---

Deploy your AVCodex agent to WhatsApp and let users interact with it directly through WhatsApp messaging. A field tech can text a photo of a Biamp Tesira fault LED and get a triage answer. An end-client in a boardroom can scan a QR code on the table and ask "why isn't the room mic picking me up?" without ever calling dispatch.

## Prerequisites

Before you begin, you'll need:

- An AVCodex agent ready to deploy
- A [Meta Developer Account](https://developers.facebook.com/)
- A phone number to associate with your WhatsApp Business account

## Setup Instructions

  **1.**
    **Create a Meta App**

    Log in to the [Meta Developer Platform](https://developers.facebook.com) and create a new app:

    1. Click **Create App**
    2. Select **Business** as the app type
    3. Fill in your app details
    4. Navigate to **WhatsApp** in the sidebar and click **Quick Start**
    5. Select **Get Started with the API** and click **Start using the API**

  **2.**
    **Open WhatsApp Configuration in AVCodex**

    Go to your AVCodex agent and click **Share** in the navigation. Find the **Deploy to WhatsApp** card and click **Add Deployment**.

  **3.**
    **Enter Your Meta Credentials**

    From the Meta Developer Platform, copy these values into the AVCodex dialog:

    - **Access Token**: Your WhatsApp API access token (at least 32 characters)
    - **Phone Number ID**: A 15-digit ID found in WhatsApp API Setup
    - **Business Account ID**: A 15-16 digit ID found in your app settings

  **4.**
    **Configure the Webhook in Meta**

    1. Copy the **Callback URL** from the AVCodex dialog
    2. In the Meta Developer Platform, go to **WhatsApp** > **Configuration**
    3. Paste the Callback URL into Meta's **Callback URL** field
    4. Copy the **Verify Token** from AVCodex and paste it into Meta's **Verify Token** field
    5. Click **Verify and Save**

  **5.**
    **Subscribe to Messages**

    In the Meta Developer Platform webhook configuration:

    1. Scroll down to find the **Webhook fields** section
    2. Find **messages** and click **Subscribe**
    3. This allows your agent to receive incoming WhatsApp messages

  **6.**
    **Save Configuration**

    Back in AVCodex, click **Save Configuration** to complete the setup.

  **7.**
    **Test Your Connection**

    1. Use the test WhatsApp number provided by Meta
    2. Send a test message like "Hello, what's the default IP for a Crestron DM-NVX-360?"
    3. Verify that your AVCodex agent responds automatically

## Going Live

When you're ready for production:

1. In the Meta Developer Platform, switch your app from **Development** to **Live Mode**
2. Complete the required business verification
3. Request the `whatsapp_business_messaging` permission
4. Add a production phone number

> **Warning:** Development mode limits you to messaging with registered test numbers only. You must go live to message any WhatsApp user, including end-clients in conference rooms.

## Managing Your Connection

### Disconnect WhatsApp

To disconnect your WhatsApp integration:

1. Go to **Share** > **Deploy to WhatsApp**
2. Click **Add Deployment** to open the dialog
3. Click **Disconnect** at the bottom

### Update Credentials

If you need to update your Access Token or other credentials:

1. Open the WhatsApp configuration dialog
2. Enter the new values
3. Click **Save Configuration**

## Best Practices

### Response Time

WhatsApp expects responses within 24 hours of the user's last message. After that, you'll need to use approved message templates for proactive outreach. For an after-hours room support hotline, this is usually fine. For proactive maintenance reminders, plan templates ahead.

### Message Templates

For proactive messaging (reaching out first), create message templates in the Meta Business Suite and get them approved before use. Common AV templates: commissioning sign-off requests, scheduled maintenance windows, room readiness check-ins.

### Rate Limits

Be aware of WhatsApp's rate limits:
- **Tier 1**: 1,000 unique users per 24 hours
- **Tier 2**: 10,000 unique users per 24 hours
- **Tier 3**: 100,000 unique users per 24 hours

You can increase your tier by maintaining good quality ratings. For most integrators, Tier 1 covers a fleet of techs and a healthy book of client rooms.

## Troubleshooting

### Messages Not Being Received

1. Verify the Callback URL is correct in Meta
2. Check that the **messages** webhook is subscribed
3. Ensure your app is in Live mode (or using test numbers in Development)
4. Verify all three credentials are valid (Access Token, Phone Number ID, Business Account ID)

### Webhook Verification Failed

1. Double-check the Verify Token matches exactly
2. Ensure your AVCodex agent is published and running
3. Try re-copying the Callback URL from AVCodex

### AI Not Responding

1. Check your AVCodex agent is active
2. Verify your AI model is configured correctly
3. Check the chat history in AVCodex's **Chats** page for any errors

### Invalid Credentials Error

- **Access Token**: Must be at least 32 characters
- **Phone Number ID**: Must be exactly 15 digits
- **Business Account ID**: Must be 15-16 digits

## Pricing

WhatsApp Business API pricing is based on conversation types:
- **User-initiated conversations**: Lower cost per conversation
- **Business-initiated conversations**: Higher cost per conversation

Prices vary by country. Check [Meta's pricing page](https://developers.facebook.com/docs/whatsapp/pricing) for current rates.

## Using with MCP

You can check WhatsApp deployment status programmatically using the AVCodex MCP Server.

### Available Tools

| Tool | Description |
|------|-------------|
| `get_whatsapp_deployment` | Get WhatsApp business configuration |

### Example Prompts

```
"Is my agent connected to WhatsApp?"
"Show me the WhatsApp configuration for my room support bot"
"What's the status of my WhatsApp deployment?"
```

### Workflow: Deployment Status

```
You: Check the WhatsApp status for my room support bot

AI: [Calls get_whatsapp_deployment]

WhatsApp Deployment:
- Status: Connected
- Phone Number ID: 123456789012345
- Business Account ID: 1234567890123456
- Mode: Production
- Last message received: 1 hour ago
```

> **Note:** MCP server access requires a Builder plan or higher. See the [MCP Setup Guide](../guides/mcp/setup.md) to get started.

*AVCodex · Your AV expertise. Amplified by AI.*