Meta Business Agent Platform

Quickstart for Meta Business Agent

Updated: Sep 18, 2026
Copy for LLM

What you’ll build

This quickstart takes you from an eligible WhatsApp Business phone number to a Meta Business Agent that answers your messages. Three API calls get you a first reply; each follow-up turn is one more call. By the end you’ll have:
  • Confirmed that your phone number can run a Meta Business Agent
  • Created an agent on that phone number
  • Held a multi-turn conversation with the agent using the Agent Test API
The Agent Test API runs your message through the full agent pipeline and returns the reply synchronously, so you don’t need a WhatsApp user on the other end. Tokens consumed while testing through this endpoint are not billed.
Important: This quickstart does not put your agent in front of WhatsApp users. The agent stays turned off, and no one messaging your business reaches it. Enabling the agent for real conversations requires billing, an app subscription, and webhook fields — see End-to-end setup for that path.

Prerequisites

  • A WhatsApp Business phone number that’s eligible for Meta Business Agent, set up in the Meta Business Agent tab of WhatsApp Manager⁠. Setting it up there is also where you accept the Meta Business Agent Terms of Service. You can run the eligibility check below before you accept — it is queryable beforehand by design — but the onboarding and agent test calls require acceptance.
  • The phone number ID for that number, shown in WhatsApp Manager under Account tools > Phone numbers. Every endpoint in this guide uses it as the entity_id path parameter.
  • A Meta app granted both the whatsapp_business_messaging and whatsapp_business_management permissions. The three calls in this quickstart need only whatsapp_business_messaging; whatsapp_business_management is required later, to read agent data, which this quickstart does not do.
  • A valid system user access token (SUAT) or Business Integration System User (BISU) token with the whatsapp_business_messaging permission — see Generate an access token. A token missing it returns 401 on the calls below.
You don’t need billing, an app subscription, webhook fields, or a consumer allowlist to complete this quickstart.
Note: Use the X-API-Version shown on each endpoint’s reference page. Meta Business Agent Platform endpoints take 2.0.0. Without the header, a request resolves to the oldest version that endpoint supports — 1.0.0 for endpoints that predate these field names — so set 2.0.0 explicitly. Cloud API endpoints differ — Thread Control, for example, takes 1.0.0.

Confirm the phone number is eligible

Check eligibility before you onboard, so you don’t chase an error later. Use the Agent Eligibility API to confirm the phone number can run an agent.

Request

curl -X GET "https://api.facebook.com/<ENTITY_ID>/agent_eligibility" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-API-Version: 2.0.0"

Response

{
  "is_eligible": true
}
If is_eligible is false, the phone number can’t run a Meta Business Agent. Check it against the eligibility criteria before continuing.

Onboard the agent

Onboarding creates the agent and its configuration on your phone number, and schedules the background jobs that prepare its data. This is the one setup call you can’t skip: until it succeeds, every other Meta Business Agent endpoint reports that no agent exists for the entity.
Use the Agent Onboarding API to create the agent, with an empty JSON body. The only body field, catalog_id, applies to Instagram agents.

Request

curl -X POST "https://api.facebook.com/<ENTITY_ID>/agent_onboarding" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-API-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

A 201 response confirms the agent was created.
{
  "agent_id": "<AGENT_ID>"
}
Save agent_id. You don’t need it for the rest of this quickstart, but the configuration endpoints accept it as a query parameter to target this agent specifically.
Onboarding schedules asynchronous data preparation, so give it a minute before you send your first message.

Send a test message

Use the Agent Test API to send the message you want the agent to answer. The agent doesn’t have to be turned on for this endpoint to work; it is used for testing before enablement.

Request

curl -X POST "https://api.facebook.com/<ENTITY_ID>/agent_test" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-API-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "user_msg": "Hi, what are your opening hours?"
  }'

Request body

FieldTypeRequiredDescription
user_msg
string
Yes
The text of the test message to send to the agent.
conversation_id
string
No
Identifier for multi-turn test conversations. Omit it to start a new conversation. See Continue the conversation.

Response

{
  "message_id": "<MESSAGE_ID>",
  "agent_response": "We're open Monday to Friday, 9 AM to 6 PM.",
  "conversation_id": "<CONVERSATION_ID>",
  "timestamp": 1756166400
}

Response fields

FieldTypeDescription
message_id
string
Unique identifier for this message exchange.
agent_response
string
The agent’s reply text.
conversation_id
string
The test conversation identifier. Pass it back to continue the conversation.
timestamp
integer
Unix timestamp of when the response was generated.
A configured agent can also return handoff, quick-reply, and product fields. For the full response shape, see the Agent Test API.
A fresh agent answers from your business’s existing information, so its first replies are general. That’s expected — you shape what it says in Next steps.

Continue the conversation

Pass the conversation_id from the previous response to send a follow-up in the same conversation, so the agent keeps the earlier turns in context.
curl -X POST "https://api.facebook.com/<ENTITY_ID>/agent_test" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-API-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "user_msg": "Are you open on Saturday too?",
    "conversation_id": "<CONVERSATION_ID>"
  }'
Each response returns the same conversation_id, so you can keep passing it to extend the conversation. Omit it whenever you want to start a clean conversation with no history.

Troubleshooting

StatusWhat it usually means
400
The entity_id isn’t a valid phone number ID, or user_msg is missing from the request body.
401
The access token is missing, expired, or lacks the whatsapp_business_messaging permission.
403
The WhatsApp Business account hasn’t accepted the Meta Business Agent Terms of Service. Onboarding and the agent test require acceptance; the eligibility check is exempt. Accept them in WhatsApp Manager⁠ — see End-to-end setup.
404
No agent exists on this phone number yet. Complete Onboard the agent.
429
You’ve exceeded the per-phone-number hourly limit on test messages. Wait and retry.
Every failure also returns a JSON error object with title and detail, plus status and an fbtrace_id you can quote to support — read detail first, as it often names the specific field or condition that failed.
Troubleshooting covers the full status-code list, connector errors and status values, and a Common issues table. Two entries there are worth knowing before you leave this quickstart:
  • Connector API calls return 400 — the connector workspace isn’t provisioned until onboarding completes. Complete Onboard the agent, then retry.
  • The agent replies here but not in live WhatsApp conversations — your app sent a message to the conversation and took control from the agent. The agent stops replying until control is released. This only affects live conversations, not the Agent Test API.

Next steps

Your agent responds. Now make it useful: