# WhatsApp Integration

Connect your Chipp AI app to WhatsApp and let users chat with your AI through WhatsApp messaging.


Deploy your Chipp AI app to WhatsApp and let users interact with your AI directly through WhatsApp messaging.

## Prerequisites

Before you begin, you'll need:

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

## Setup Instructions

<Steps>
  <Step title="1">
    <strong>Create a Meta App</strong>

    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**
  </Step>

  <Step title="2">
    <strong>Open WhatsApp Configuration in Chipp</strong>

    Go to your Chipp application and click **Share** in the navigation. Find the **Deploy to WhatsApp** card and click **Add Deployment**.
  </Step>

  <Step title="3">
    <strong>Enter Your Meta Credentials</strong>

    From the Meta Developer Platform, copy these values into the Chipp 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
  </Step>

  <Step title="4">
    <strong>Configure the Webhook in Meta</strong>

    1. Copy the **Callback URL** from the Chipp 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 Chipp and paste it into Meta's **Verify Token** field
    5. Click **Verify and Save**
  </Step>

  <Step title="5">
    <strong>Subscribe to Messages</strong>

    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 app to receive incoming WhatsApp messages
  </Step>

  <Step title="6">
    <strong>Save Configuration</strong>

    Back in Chipp, click **Save Configuration** to complete the setup.
  </Step>

  <Step title="7">
    <strong>Test Your Connection</strong>

    1. Use the test WhatsApp number provided by Meta
    2. Send a test message like "Hello"
    3. Verify that your Chipp AI responds automatically
  </Step>
</Steps>

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

<Callout type="warning">
Development mode limits you to messaging with registered test numbers only. You must go live to message any WhatsApp user.
</Callout>

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

### Message Templates

For proactive messaging (reaching out first), create message templates in the Meta Business Suite and get them approved before use.

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

## 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 Chipp app is published and running
3. Try re-copying the Callback URL from Chipp

### AI Not Responding

1. Check your Chipp app is active
2. Verify your AI model is configured correctly
3. Check the chat history in Chipp'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.