|
| 1 | +--- |
| 2 | +title: WhatsApp Embedded Signup |
| 3 | +description: Set up WhatsApp integration using Meta's streamlined embedded signup flow |
| 4 | +sidebarTitle: WhatsApp Embedded Signup |
| 5 | +--- |
| 6 | + |
| 7 | +WhatsApp Embedded Signup enables users to connect their WhatsApp Business accounts through Meta's streamlined OAuth flow without manual webhook configuration. This significantly improves the user experience by automating the entire setup process. |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +1. A valid Facebook account |
| 12 | +2. A WhatsApp Business account (or ability to create one) |
| 13 | +3. Admin access to your Chatwoot installation |
| 14 | + |
| 15 | +## Super Admin Configuration |
| 16 | + |
| 17 | +Before users can use WhatsApp Embedded Signup, administrators must configure the following environment variables via the Super Admin panel at `/super_admin/app_config?config=whatsapp_embedded`: |
| 18 | + |
| 19 | +- **WHATSAPP_APP_ID**: The Facebook App ID for WhatsApp Business API integration |
| 20 | +- **WHATSAPP_CONFIGURATION_ID**: The Configuration ID for WhatsApp Embedded Signup flow (obtained from Meta Developer Portal) |
| 21 | +- **WHATSAPP_APP_SECRET**: The App Secret for WhatsApp Embedded Signup flow (required for token exchange) |
| 22 | + |
| 23 | +<Note> |
| 24 | +These settings must be configured by a Super Admin before the WhatsApp Embedded Signup option becomes available to users. |
| 25 | +</Note> |
| 26 | + |
| 27 | +### Retrieving Configuration Values from Meta Developer Portal |
| 28 | + |
| 29 | +To obtain the required configuration values: |
| 30 | + |
| 31 | +#### 1. Create or Access Your Facebook App |
| 32 | + |
| 33 | +1. Go to [Meta for Developers](https://developers.facebook.com/) |
| 34 | +2. Click on "My Apps" in the top navigation |
| 35 | +3. Either select an existing app or click "Create App" |
| 36 | +4. If creating a new app: |
| 37 | + - Choose "Business" as the app type |
| 38 | + - Select "Business" for "I want to connect my app to" |
| 39 | + - Provide app details (name, email, business portfolio) |
| 40 | + |
| 41 | +#### 2. Configure WhatsApp Product |
| 42 | + |
| 43 | +1. In your app dashboard, click "Add Product" |
| 44 | +2. Find "WhatsApp" and click "Set Up" |
| 45 | +3. Accept the WhatsApp Business Terms |
| 46 | + |
| 47 | +#### 3. Retrieve App ID and App Secret |
| 48 | + |
| 49 | +- **App ID**: Found at the top of your app dashboard or in Settings → Basic |
| 50 | +- **App Secret**: Located in Settings → Basic (click "Show" and authenticate to reveal) |
| 51 | + |
| 52 | + |
| 53 | +#### 4. Obtain Configuration ID |
| 54 | + |
| 55 | +1. Navigate to WhatsApp → Configuration in the left sidebar |
| 56 | +2. Under "Embedded signup", click "Configure" |
| 57 | +3. Set up the configuration: |
| 58 | + - **Callback URL**: `https://your-domain.com/webhooks/whatsapp/{phone_number_id}` |
| 59 | + - **Success URL**: `https://your-domain.com/app/accounts/{account_id}/settings/inboxes/new/whatsapp_cloud` |
| 60 | + - **Cancel URL**: `https://your-domain.com/app/accounts/{account_id}/settings/inboxes/list` |
| 61 | +4. Save the configuration |
| 62 | +5. Copy the generated **Configuration ID** |
| 63 | + |
| 64 | +<Warning> |
| 65 | +**Important:** Before overriding the current callback URI, your app must be subscribed to receive messages for the WhatsApp Business Account. This prevents error (#100) during webhook configuration. Ensure the messages webhook field is subscribed in your app's webhook settings. |
| 66 | +</Warning> |
| 67 | + |
| 68 | + |
| 69 | +#### 5. Required Permissions |
| 70 | + |
| 71 | +Ensure your app has the following permissions enabled: |
| 72 | + |
| 73 | +- `whatsapp_business_management` - Manage WhatsApp business assets |
| 74 | +- `whatsapp_business_messaging` - Send and receive WhatsApp messages |
| 75 | +- `business_management` - Manage business assets |
| 76 | + |
| 77 | + |
| 78 | +<Note> |
| 79 | +For production use, your app may need to go through App Review to get advanced access to certain features. The embedded signup flow works with Standard Access for most use cases. |
| 80 | +</Note> |
| 81 | + |
| 82 | +## Creating a WhatsApp Channel |
| 83 | + |
| 84 | +### Step 1: Navigate to Channel Selection |
| 85 | + |
| 86 | +1. Go to Settings → Inboxes in your Chatwoot dashboard |
| 87 | +2. Click on "Add Inbox" |
| 88 | +3. Select WhatsApp from the channel options |
| 89 | + |
| 90 | + |
| 91 | + |
| 92 | +### Step 2: Choose WhatsApp Cloud |
| 93 | + |
| 94 | +Select "WhatsApp Cloud" for the quick setup through Meta (embedded signup). |
| 95 | + |
| 96 | + |
| 97 | + |
| 98 | +### Step 3: Start Embedded Signup |
| 99 | + |
| 100 | +Click on "Connect with WhatsApp Business" to begin the embedded signup flow. |
| 101 | + |
| 102 | + |
| 103 | + |
| 104 | +### Step 4: Facebook Authentication |
| 105 | + |
| 106 | +You'll be redirected to Facebook to authenticate. You need to log in with an existing Facebook account. |
| 107 | + |
| 108 | + |
| 109 | + |
| 110 | +### Step 5: Fill Business Information |
| 111 | + |
| 112 | +Select an existing business portfolio or create a new one to add your phone number. Fill in the required business information: |
| 113 | + |
| 114 | +- Business portfolio |
| 115 | +- Business name |
| 116 | +- Business website or profile page |
| 117 | +- Country |
| 118 | +- Address (optional) |
| 119 | + |
| 120 | + |
| 121 | + |
| 122 | +### Step 6: Select WhatsApp Business Account |
| 123 | + |
| 124 | +Choose an existing WhatsApp Business account or create a new one. You can also select or create a WhatsApp Business Profile. |
| 125 | + |
| 126 | + |
| 127 | + |
| 128 | +### Step 7: Complete Setup |
| 129 | + |
| 130 | +Once you've completed all steps, you'll see the success screen. Your WhatsApp Business account is now connected and ready to receive messages. |
| 131 | + |
| 132 | + |
| 133 | + |
| 134 | + |
| 135 | + |
| 136 | +## Key Features |
| 137 | + |
| 138 | +- **No manual configuration required**: The entire webhook and phone number setup is automated |
| 139 | +- **Secure OAuth based authentication**: Uses Meta's official OAuth 2.0 flow |
| 140 | +- **Automatic webhook and phone number configuration**: Webhooks are registered automatically |
| 141 | +- **Real-time progress tracking**: Visual feedback during the signup process |
| 142 | +- **Comprehensive error handling**: Clear error messages and guidance |
| 143 | + |
| 144 | +## Commerce Policy Compliance |
| 145 | + |
| 146 | +Meta will review your business to ensure it complies with WhatsApp's Commerce Policy and will reach out within 24 hours if there's an issue. |
| 147 | + |
| 148 | +## Reference Documentation |
| 149 | + |
| 150 | +For more technical details about WhatsApp Embedded Signup, refer to the official Meta documentation: |
| 151 | +- [WhatsApp Embedded Signup - Meta for Developers](https://developers.facebook.com/docs/whatsapp/embedded-signup/) |
| 152 | + |
| 153 | +## Troubleshooting |
| 154 | + |
| 155 | +### Common Issues |
| 156 | + |
| 157 | +1. **"WhatsApp Embedded Signup not available"** |
| 158 | + - Ensure your Super Admin has configured the required environment variables |
| 159 | + - Check that all three values (App ID, Configuration ID, and App Secret) are properly set |
| 160 | + |
| 161 | +2. **Authentication Errors** |
| 162 | + - Make sure you're using an existing Facebook account |
| 163 | + - Verify you have the necessary permissions for the business |
| 164 | + |
| 165 | +3. **Business Verification Issues** |
| 166 | + - Ensure your business information is accurate and complete |
| 167 | + - Check that your business complies with WhatsApp's Commerce Policy |
| 168 | + |
| 169 | +### Getting Help |
| 170 | + |
| 171 | +If you encounter issues during setup: |
| 172 | + |
| 173 | +1. Check the Chatwoot logs for any error messages |
| 174 | +2. Verify all environment variables are correctly configured |
| 175 | +3. Ensure your Facebook/WhatsApp accounts meet the prerequisites |
| 176 | +4. Contact Chatwoot support with specific error messages if the issue persists |
0 commit comments