Home
Guides

Meta Business Agent (MBA) API overview

A practical overview of onboarding, configuring, and operating a Meta Business Agent for a Partner Portal app, with workflow guidance and endpoint caveats.

Meta Business Agent (MBA) API overview

The Meta Business Agent API lets you set up and operate an agent for a Partner Portal app. The API is organized around the app, with resources for agent settings, knowledge, skills, connectors, events, evaluations, and conversation handoff.


What can MBA do?


  • You configure what your agent knows, how it responds, and what actions it can take — plus handoff to your app whenever you need to step in.
  • Add knowledge — business information, FAQs, websites, and files so the agent answers from your content
  • Define how it responds — instructions that set the agent’s tone, priorities, and brand voice
  • Connect your systems — your own APIs and webhook subscriptions so the agent can take actions and listen to events, such as booking an appointment or confirming a payment
  • Hand off to your app — pass control between the agent and your app for specific events or flows
  • Test your agent — send test messages and evaluate performance before and after you go live

See its detailed capabilities as defined by Meta


Which phone numbers are eligible

Before you can set up Meta Business Agent on a phone number, that number must be eligible. A phone number’s WhatsApp Business account must meet all of the following:

  • In a supported vertical — all verticals are supported except Finance, Government, Health, Alcohol, Gambling, over-the-counter drugs, and matrimony services. The account must have a valid business category set.
  • Managed through the WhatsApp Business Platform — the phone number belongs to an enterprise WhatsApp Business Platform account (including one managed through a Solution Partner or Embedded Signup), not the consumer WhatsApp Business app.
  • In good standing — neither the WhatsApp Business account nor its owning business is restricted or banned on WhatsApp.
  • In an eligible country — the business must be based in a country authorized for Meta Business Agent.
    Meets business trust and verification requirements.
  • Not already running another AI agent on that number — an active authorized-agent integration blocks Meta Business Agent.
  • Additional account and integrity conditions can also affect eligibility. The Eligibility endpoint is the authoritative check — call it to confirm whether a specific phone number is eligible.

Meta ToS

Meta Business Agent rejects API calls until you (Tech Provider) and customers accept the required Terms of Service.


Billing Setup

Turning your agent on for everyone — ai_audience set to EVERYONE — requires a payment method; without one, the settings call to enable the agent for everyone fails with a 400 error. You can turn the agent on with ai_audience set to ALLOWLISTED_ONLY without a payment method, so you can test with allowlisted consumers first before expanding to EVERYONE.

Read the Meta doc here to know how to setup payment



Before you begin

  • Send the Universal App Token in the Authorization header. The reference accepts the raw token; Bearer <token> is also accepted.
  • Use the Partner Portal appId (UUID) in the path. It identifies the app and maps to Meta's entity ID.
  • The app must be live and have a phone number attached. Requests can fail if either readiness check is not met.
  • Most endpoints under /bizai/** are limited to 30 requests per app per 60 seconds. The next request is rejected with 429 Too Many Requests.

Recommended setup

  1. Check eligibility. Call Get agent eligibility before onboarding. It reports whether the app is eligible; it does not return a reason when the result is false.
  2. Create the agent once. Use Onboard an agent. It returns a Meta agent_id (pfbid…). Each call creates a new agent, and there is no delete-agent endpoint, so do not retry onboarding as a routine recovery step.
  3. Configure settings. Use Get agent settings and Update agent settings to control rollout, audience, handoff, follow-up messages, and phrases the agent must avoid. Enabling rollout for consumers requires a payment method. An allowlisted-only audience does not require one. The documented agent_id query parameter on settings reads is currently accepted but ignored.
  4. Add knowledge. Business information can be read, replaced, or reset through Business Info. FAQs support list, create, read, update, and delete operations. Files can be listed, read, and deleted; websites can be added, listed, read, updated, and deleted. Website crawling is asynchronous.
  5. Shape the agent. Agent Skills are free-text behavior instructions reviewed by Meta. UI Skills define when the agent renders a WhatsApp interactive component. A UI skill that uses a Flow needs the Flow published before the skill can be enabled.
  6. Connect external systems. Connectors hold an external service configuration and its credentials. Add connector tools to define individual operations the agent can call. API keys, OAuth credentials, and client certificates have dedicated upsert endpoints; secrets and private keys are write-only. Refresh MCP tools after configuring an MCP connector.
  7. Test and operate. Send an agent test message uses testing tokens, which are not billed; test conversations cannot be deleted. Agent events can notify the agent of events such as a payment, and can send a real WhatsApp message to the supplied number. Evaluation endpoints list cases, submit a run, poll its job, and retrieve per-conversation details or aggregate summaries. Use Thread Control to pass a live WhatsApp conversation between the primary app and the AI agent.

Reference index

Updated about 12 hours ago

Did this page help you?