For the complete documentation index, see llms.txt. This page is also available as Markdown.

Known limitations

Meta Business Agent is in early access, and we found a number of gaps while testing. This page collects them all in one place so you can plan around them. Each is also flagged inline on the relevant step. We've raised the significant ones with Meta and expect fixes over time — check back for updates.

Errors and retries

Gap
What to do

Meta replaced most unexplained 500 errors with specific codes during October 2026: 400 (content or configuration problem, e.g. Content rejected), 403 (not authorized for that business, or capability not enabled), 404 (id doesn't exist, or no agent on the number), 409 (concurrent write).

Read the status code first. 400, 403 and 404 won't succeed if retried unchanged; fix the request. 409 can be retried as sent. Only retry 429 and 500 later. If a 500 persists for a day, contact support.

Rate limits are counted per app and per business, about 1,000 requests per hour per operation for most endpoints. agent_test is limited to about 500 per hour per number.

Back off on 429 until the limit resets.

Error responses carry an fbtrace_id, and successful thread control responses a request_id.

Include them when contacting support about a specific request.

Eligibility & access

Gap
What to do

Agent API calls return 403 until the Meta Business AI Terms are accepted for the WABA. The eligibility check is the exception and works before acceptance.

Accept the terms in Business Manager → WhatsApp Manager → Business AI. Only someone with access to the WABA's owning business can accept. See Enable and accept terms.

Eligibility check could return HTTP 500 for a non-eligible number, or 403 before terms acceptance. Resolved — it now returns is_eligible, with an ineligibility_reason when false.

Availability was regional during rollout (Brazil first, EU mid-July 2026). The restriction appears lifted.

If a new-region number reads not-eligible, region may still be the cause — re-check after a short wait.

CORS blocks browser calls to Meta's agent endpoints.

Call the API from a backend, not directly from a browser. (With 360dialog, keep your D360-API-KEY server-side anyway.)

Enabling the agent returns 400 while Meta's WhatsApp Business Inbox is in use on the WABA or another WABA in the same business portfolio, or when conversation routing must be configured first.

Remove Inbox from that account, or follow the routing guidance linked in the error. See If enabling the agent fails.

Testing

Gap
What to do

agent_test only returned replies when the agent was fully published (EVERYONE). Resolved — agent_test now replies before go-live and under ALLOWLISTED_ONLY.

Test with agent_test right after configuring. See Test your agent.

Each agent_test call starts a fresh conversation unless you pass back a conversation_id; the to field is ignored.

Capture conversation_id from the first response to continue a multi-turn test.

Allowlist

Gap
What to do

The allowlist holds up to 20 entries per phone number. Adding to a full list returns 400.

Remove entries you no longer need. For wider tests, roll out to EVERYONE on a dedicated test number.

Entries added by consumer_bsuid have no consumer_phone_number, and the other way round.

Handle either field being absent when reading the list.

Conversation, handoff & context

Gap
What to do

Once the agent hands off to a human, it stops answering that chat.

Make sure a human handover path is live before launch — otherwise those customers get no reply.

On hand-back, the agent loses earlier conversation context.

Don't assume continuity across a human handoff; re-establish context if needed.

The handoff notice is the fixed message you define — it can't be adapted per customer language.

For multilingual audiences, keep the handoff message simple or language-neutral.

The agent doesn't always reply in the customer's language.

Reinforce language behavior in your skills where it matters.

The agent can't read videos, documents (PDF, CSV, Office files) or audio files that customers send. Images (with their caption) and voice notes (as a transcript) are read. The agent is told it received something it can't read, so it can ask for another format.

Upload documents the agent needs as knowledge files. Voice notes are enabled per phone number, so test them on the number your agent runs on.

No API to read who currently holds the conversation (thread owner).

Track it from the standby vs messages routing and messaging_handovers events. See Thread control.

take is reserved for the number's escalation partner. Your app takes control by sending a message.

Hand a conversation back with pass (target_role: "ai_agent"), or release it to idle. See Thread control.

release returns the conversation to idle, not straight to the agent, and emits no messaging_handovers event.

Use pass with target_role: "ai_agent" when you want the agent to own the conversation right away.

Configuration

Gap
What to do

A skill that fails Meta's automated review is saved with status: blocked and never applied, even though create returned 201.

Check status after every create or edit. See Skills.

Updating an FAQ can change its id.

Store the id from the update response. See FAQs.

A website crawl can finish with completed_no_data when nothing useful could be extracted.

Point the agent at more specific pages, or add the facts as FAQs.

Files

Gap
What to do

file_name should include the file extension.

Ensure file_name is added when uploading files, including the file extension. Example: file_name="sample.pdf"

CSV files, and tables inside PDFs, error out when read.

Put structured/tabular facts into FAQs or business info instead.

Uploads are multipart/form-data, max 100 MB.

Keep files within the limit.

The agent can't reliably send files or images out to customers.

This can be achieved now with interactive messages, including images and videos.

Events

Gap
What to do

agent_event (proactive outbound) only works while the agent is on-call (holds the conversation). Status is poll-only (request_received → processing → sent/failed/skipped/success).

Only trigger events when the agent holds the thread; poll for status. A failed event's error_message says why. See Agent events.

Webhooks

Gap
What to do

The agent's standby conversation was not delivered to per-number webhooks. Resolved — 360dialog now routes standby to your number's webhook, re-signed with x-360dialog-signature.

messaging_handovers events aren't forwarded to your webhook yet. We're fixing this.

Track who holds a conversation from the standby vs messages routing until it ships.

No webhook when the agent is switched on or off.

Read GET /agent_config/settings when you need to know. See Check whether the agent is on.

API response shapes

Gap
What to do

settings, skills, faq, websites, files, and allowlist return bare arrays, not { "data": [ ... ] }. settings is a single-element array. Lists aren't paged.

Parse accordingly.

Ids (skills, FAQs, websites, allowlist entries, connectors) aren't plain numbers or UUIDs.

Pass them back exactly as returned.

business_info is a closed six-field object — no custom keys.

Use FAQs/files for anything that doesn't fit the six fields.

Connectors

Gap
What to do

MCP connectors are not available yet (on Meta's roadmap).

Integrate via the REST connector + tool model for now. See Configure your agent.

Billing

Gap
What to do

Since 1 August, Meta required a client credit line for all MBA usage, including allowlisted testing. Resolved — ALLOWLISTED_ONLY no longer requires a payment method.

Test freely on an allowlist without a payment method; only add one before switching to EVERYONE.

A payment method is still required before opening the agent to EVERYONE — a credit line, or a credit card where Meta has enabled it for the account (rolling out gradually since September 2026).

Apply for/add a credit line via Billing Hub, or check whether card payment is available for your account. See Roll out to everyone.

MBA is billed by Meta directly, postpaid, at the start of the following month. If credit-line utilization hits 100%, MBA access is suspended until resolved.

Track spend with the usage insights endpoint and set a usage budget to cap exposure. Resolve utilization promptly.

MBA usage doesn't appear in the standard WhatsApp billing analytics.

Pull billable messages, billable tokens and cost with the usage insights endpoint. See Track usage and spend.

The usage endpoint needs your billable account ID (entity_id), which can't be retrieved through the API.

Copy it once from Meta's Billing Hub under Accounts > Meta Business Agent accounts and keep it with your configuration.

Usage budgets and invoices count tokens differently. A budget caps the tokens the agent consumes; the usage endpoint and your invoice report billed tokens, which Meta normalizes and can be lower.

Don't expect a token budget to match the billed tokens you see. Use the usage endpoint for what you'll pay, and budgets as a hard cap on consumption.

No published guidance from Meta on how quickly usage appears in the usage endpoint.

Don't assume the endpoint is real time. Re-check recent periods before using them to reconcile spend.


Last reviewed: 10 Nov 2026, against Meta's changelog up to 6 Nov 2026. Behaviors above may change as Meta ships fixes.

Last updated

Was this helpful?