Meta Business Agent — Allowlist & Testing Explained

Meta's Business Agent API gives you two features that most teams miss until they're already live and it's too late — the Allowlist (who is allowed to talk to your agent) and Agent Test (a way to try the agent end-to-end without spending a rupee on tokens). Here's exactly what they do and how to use them.

Part 1 — The Allowlist

What it does

When your agent's AIAudience setting is ALLOWLISTED_ONLY, only the WhatsApp numbers (or Instagram usernames) you've added will actually receive AI replies. Everyone else falls through — as if the AI wasn't there.

Why it matters

• Pilot safely. Roll the agent out to your own team and a few friendly customers first.
• Limit blast radius. If prompts go wrong, only a handful of people see it.
• Staged launches. Add users in waves — 10, 100, 1,000 — instead of turning it on for everyone at once.

The three operations

Add a consumer

POST https://api.facebook.com/{PHONE_NUMBER_ID}/agent_config/allowlist
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "consumer_phone_number": "+923001234567"
}

Instagram works the same way — swap consumer_phone_number forconsumer_instagram_username (no @).

Required permissions

• bizai_wa_enterprise_api_3p_access or bizai_ig_enterprise_api_3p_access
• Or the whatsapp_business_messaging / instagram_basic permission

Part 2 — Agent Test

What it does

Sends a test message straight into your agent's brain — through the full pipeline — without needing a real customer phone number. The response comes back exactly like it would in production: reply text, quick replies, product references, even handoff reasons.

The best part: token usage during testing isn't billed.

Sample request

POST https://api.facebook.com/{PHONE_NUMBER_ID}/agent_test
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "user_msg": "What are your store hours?",
  "conversation_id": "conv_123abc"
}

Sample response

{
  "message_id": "msg_456def",
  "agent_response": "We're open Monday–Friday, 9am–6pm.",
  "conversation_id": "conv_123abc",
  "timestamp": 1699564800,
  "quick_replies": ["Hours", "Location", "Contact us"],
  "product_variant_ids": []
}

What each field means

• message_id — unique id for this exchange
• agent_response — the AI reply
• conversation_id — pass this back on the next call to keep context
• quick_replies — suggested follow-ups the UI can render as chips
• handoff_reason — appears when the agent decides to transfer to a human
• no_response_reason — e.g. ELIGIBILITY_CHECK_FAILED when the agent won't reply

A launch checklist

1. 1Build your agent and set AIAudience to ALLOWLISTED_ONLY.
2. 2Add your own number to the allowlist. Send yourself a real message.
3. 3Run agent_test with 5–10 tricky prompts (rude questions, refunds, edge cases).
4. 4Add 3–5 friendly customers. Watch the transcripts for a week.
5. 5Widen the allowlist in waves. When confident, switch AIAudience to open.

How Teambox handles this for you

Wiring these two endpoints into your own code takes hours. In Teambox, both are already built in — add allowlisted numbers from a table, and hit Test agent to run a conversation in a preview window before you ever go live. Your customers see a polished agent, and you see the whole rollout under control.

Ready to try it? Start free — the allowlist and test tools work on every plan, from day one.