End-to-end setup

• A WhatsApp Business account (WABA) ID, found in WhatsApp Manager⁠ in Settings > WhatsApp accounts
• Your Business Portfolio (Meta Business Account) ID, found in the Meta Business Suite⁠ as the business_id parameter in the URL
• An App ID for your Meta app, found in the Facebook Developer Portal next to your app’s name
• The whatsapp_business_messaging permission granted to your app
• A WhatsApp Business phone number that’s eligible for Meta Business Agent

1. Go to WhatsApp Manager⁠ and select the correct WhatsApp Business account if prompted.
2. Go to the Meta Business Agent tab. This tab only appears if at least one phone number in your WABA is eligible.
3. Set up Meta Business Agent for any eligible phone numbers. This is also where you accept the Meta Business Agent Terms of Service.
4. Your agent isn’t enabled yet — set up its knowledge and skills first (see Next steps) before enabling it.

Important: Solution Partners and Tech Providers: your client accepts the Meta Business Agent Terms of Service in WhatsApp Manager (above). You must additionally accept the Tech Provider Terms of Service (if you haven’t already done so) by becoming a Tech Provider in the Facebook Developer Portal. Meta Business Agent rejects API calls until you accept the required Terms of Service. For details, see Get started for Tech Providers.

1. Go to Meta Business Suite⁠.
2. In the left navigation, select Settings.
3. In the side navigation panel, under Users, select System users.
4. In the upper right, click the + Add button. In the dialog that opens, enter a name, select the Admin role, and click Create system user.

1. In Meta Business Suite⁠, in the left navigation, select Settings. In the side navigation panel, under Users, select System users, then select your system user.
2. In the upper right, click the three-dot menu button and click Assign Assets.
3. In the panel that opens, select Apps, find your app, and enable the checkbox next to it.
4. Assign the permissions that are necessary for your System User.
5. Find your WABA, and enable the checkbox next to it.
6. Click the slider next to View and manage phone numbers to grant the permission, and then click Assign Assets.

Note: Include the X-API-Version: 2.0.0 header on every Meta Business Agent Platform API request. Without it, requests default to version 1.0.0, where the Skills endpoint is unavailable (it was named instructions before version 2.0.0).

1. In Meta Business Suite⁠, in the left navigation, select Settings. In the side navigation panel, under Users, select System users, then click your system user.
2. In the upper right, click Generate new token. A dialog opens.
3. In the dialog, select your app from the dropdown, and then click Next.
4. Select the token expiration setting, and then click Next.
5. Click the checkboxes next to the following permissions:
   • whatsapp_business_messaging
   • whatsapp_business_management
6. Click Generate token and save it in a secure location.

1. Go to the Graph API Explorer tool.
2. Choose your app from the dropdown menu and select Get App Token. This opens a dialog to choose the Business Portfolio and the specific WhatsApp account. Make sure you choose the correct WABA.
3. Make a POST request to /<WABA_ID>/subscribed_apps. See the Subscribed Apps API reference for details.
4. Verify the subscription by making a GET request to /<WABA_ID>/subscribed_apps. If successful, your app ID appears in the response.

1. Go to the Facebook Developer Portal and click your app.
2. In the left navigation, go to the WhatsApp tab, then go to Configuration. The configuration page opens.
3. In the Webhook fields section, click Subscribe next to each of the following fields:
   • messages
   • standby
   • messaging_handovers

curl -X POST "https://graph.facebook.com/v21.0/<PHONE_NUMBER_ID>/thread_control" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-API-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "action": "release",
    "to": "<CONSUMER_PHONE_NUMBER>"
  }'

{
  "messaging_product": "whatsapp"
}

• Your human agent resolves the customer’s issue and no further action is needed
• You want the AI agent to handle routine follow-ups automatically
• The conversation requires capabilities the agent provides (product recommendations, FAQ responses)

curl -X POST "https://graph.facebook.com/v21.0/<PHONE_NUMBER_ID>/thread_control" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-API-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "action": "take",
    "to": "<CONSUMER_PHONE_NUMBER>",
    "metadata": "Human agent stepping in"
  }'

{
  "messaging_product": "whatsapp"
}

{
  "type": "control_taken",
  "control_taken": {
    "previous_owner_app_id": "<APP_ID>",
    "new_owner_app_id": "<APP_ID>",
    "new_owner_business_id": "<BUSINESS_ID>",
    "metadata": "Human agent stepping in"
  }
}

1. Add each consumer to the allowlist with POST /{entity_id}/agent_config/allowlist, passing consumer_phone_number in E.164 format, for example +15551234567. Add one consumer per call, and list the current entries with GET /{entity_id}/agent_config/allowlist.
2. Set ai_audience to ALLOWLISTED_ONLY with PUT /{entity_id}/agent_config/settings, then read the setting back with GET /{entity_id}/agent_config/settings to confirm the change applied.