Productos AI
Technical

Meta Business Agent Platform: API, connectors and conversation control

The difference between an agent that answers well and one that resolves lives in this layer: your own knowledge, tools that hit your systems, and a human handoff that genuinely works.

  • Knowledge, instructions, connectors, webhooks, testing and evaluation
  • Real conversation control between the agent and your application
  • Multi-client pattern for Meta technology partners

Last updated: September 2026

The short answer

Meta Business Agent Platform is the API layer used to configure and operate the WhatsApp agent: you load knowledge into it, set brand instructions, declare your own APIs as tools, subscribe webhooks, and govern who controls each conversation, the agent or your application.

The platform covers WhatsApp only today, on the Cloud API. Switching the agent on from the WhatsApp Business app gives access to none of these surfaces.

Source: official Meta Business Agent Platform documentation, 2026.

Requirements and access

Before the first API call, the boring part has to be settled, and that is where most integrations stall.

  • A WhatsApp Business Account with a number eligible for the agent
  • A Meta app with the WhatsApp Business messaging and management permissions
  • A system user with the Admin role, with the app and the WhatsApp Business Account assigned
  • An active payment method in the Billing Hub: without it messages are not delivered
  • The app subscribed to the WhatsApp Business Account

The detail that breaks integrations: the API version

This is the platform's quietest failure and it costs hours of debugging.

  • The API version 2.0.0 header must be sent on every request
  • If it is omitted, the request falls back to version 1.0.0
  • On version 1.0.0 the agent instructions endpoint does not exist, so the call fails for no visible reason

Knowledge: where the answers come from

Knowledge is not one giant prompt: it is four distinct surfaces, maintained separately and auditable.

  • Business information: the core facts it answers from
  • FAQs: question and answer pairs you control
  • Websites: URLs the platform crawls to extract content
  • Files: documents uploaded as a knowledge source
  • Knowledge insights show what is being used and what is not, which is the basis for fixing bad answers

Instructions: voice and limits

This is where the agent's behavior is defined. It is the equivalent of system instructions, and it is what separates a brand agent from a generic bot.

  • Tone and style of the replies
  • What it prioritizes when several answers are possible
  • What it must never say, and when it should escalate instead of improvising
  • Short, concrete replies, which also cut token consumption

Connectors and tools: where the agent stops talking and starts doing

A connector is the definition of an external API. Its tools are the concrete operations the agent may call during a conversation.

  • You declare the connector with your API definition
  • You declare its tools: look up an order, check stock, find calendar slots, create a booking
  • The agent decides when to call them based on the conversation
  • Meta also ships connections to hundreds of third-party systems, naming Shopify, Zendesk and Shopee among them

Webhooks and conversation control

This is the most underestimated block. Without it, human escalation is a message asking the customer to call you.

  • Three webhook fields get subscribed: messages, standby and handover changes
  • By default the agent replies and your application watches the conversation in standby
  • Your application takes thread control with an explicit action, or implicitly by sending a message
  • Once the case is closed, it releases control and the agent resumes replying
  • Every control change arrives by webhook, so who handled what and when is on record

Testing, evaluation and insights

The platform lets you validate the agent before it ever talks to a real customer. Skipping this is the fastest way to burn trust in the channel.

  • Send test messages against the configured agent
  • Evaluate performance before and after going live
  • Knowledge usage insights to spot gaps
  • Events pushed from your system so the agent reacts to changes in your operation

Controlled launch with an allowlist

The sensible way to go live: the agent enabled, but talking only to whoever you decide.

  • Authorized numbers are loaded in international E.164 format
  • The agent's audience is set to allowlisted only
  • The agent is enabled only after both of those are in place
  • By default the audience is everyone and the allowlist is ignored, so the order matters

The technology partner pattern

If the integration serves several clients, the credential model changes and it is worth setting up properly from the first project.

  • A direct integrator uses its own system user token
  • A technology partner operating on behalf of third parties uses a business integration system user token
  • That pattern makes it possible to manage many client accounts without sharing credentials between them
  • It is the model we work with as a Meta Tech Provider

Endpoint reference

The platform's real sequence, grouped by phase.

GET /agent_config/eligibility

Phase
Onboard
What it does
Check whether the number can have an agent

POST /agent_config

Phase
Onboard
What it does
Onboard the agent, required before enabling it

PUT /agent_config/settings

Phase
Onboard
What it does
Enable the agent and configure its behavior

PUT /agent_config/skills

Phase
Configure
What it does
System instructions: tone, priorities and limits

POST /agent_config/knowledge/business_info

Phase
Configure
What it does
Business information

POST /agent_config/knowledge/faqs

Phase
Configure
What it does
Question and answer pairs

POST /agent_config/knowledge/websites

Phase
Configure
What it does
URLs the platform crawls

POST /agent_config/knowledge/files

Phase
Configure
What it does
Files as a knowledge source

POST /agent_config/connectors

Phase
Configure
What it does
Declare an external API as a connector

POST /agent_config/connectors/{id}/tools

Phase
Configure
What it does
Operations the agent may call

POST /{phone-number-id}/thread_control

Phase
Operate
What it does
Take or release conversation control

POST /agent_config/events

Phase
Operate
What it does
Trigger agent actions from your system

POST /agent_config/test

Phase
Operate
What it does
Send test messages

POST /agent_config/eval

Phase
Operate
What it does
Evaluate the agent's performance

GET /agent_insights

Phase
Operate
What it does
Review knowledge usage

POST /{entity-id}/agent_config/allowlist

Phase
Operate
What it does
Restrict the audience to specific numbers

Paths per Meta's official documentation as of September 2026. The platform moves fast: always verify against the current reference.

Frequently asked questions

Yes, if you are integrating for your own business: a Meta app with the right permissions and a system user is enough. The technology partner pattern becomes necessary when you operate third-party accounts and need credentials separated per client.

It depends on the tools you declare. A connector can expose read operations, such as looking up an order, and write operations, such as creating a booking. The surface is whatever you decide, and that is exactly where the limits belong.

From the webhooks. Messages the agent handles arrive on the standby field, and every control change is notified in its own event. Sending a message from your application takes control implicitly.

Not simultaneously. One number cannot run several messaging products at once. What you can do is split by number, or use conversation control so the agent and your application alternate on the same thread.

The agent loses the data it was about to fetch, so the failure strategy has to be designed: escalate to a person, answer with a safe fallback, or ask to retry. That is part of the integration design, not something the platform solves on its own.

Yes. There is an evaluation endpoint to measure performance and an insights endpoint that shows which knowledge is being used. That combination is what lets you fix bad answers instead of guessing.

Shall we integrate it with your systems?

Tell us which APIs you have and what the agent should resolve, and we come back with the connector design, conversation control model and test plan.

Integrate your API with the agent?

We will talk to your engineers

Let's talk