Added Multi-item cart management, a use case guide for letting shoppers build a basket across several turns of a conversation. The guide covers holding the cart in your own system rather than in the conversation, the connector tools that add, change, and remove lines, and the agent instructions that stop the agent quoting a total or a stock level no tool returned.

Added Order status checks, a use case guide for answering “where is my order?” from live fulfilment data. The guide covers identifying the right order without asking the customer for a reference, deciding how much detail a phone number match alone may release, translating carrier states into plain answers, and escalating a stalled order to a person.

Corrected the documented format of the connector_id path parameter and the tool_id query parameter on Connectors. The reference page showed plain numeric examples for both, and for the id field returned when a connector is created or listed, but the endpoints expect the id value exactly as the API returns it. Pass that value through unchanged when reading, updating, or deleting a connector, when configuring its credentials, and when filtering connector logs to a single tool. Only the documentation changed — the endpoints have always behaved this way. The page also now states the request budget of 1000 requests per hour.

Corrected the documented format of the skill_id path parameter on Agent Skills. The reference page described skill_id as a UUID and showed a UUID example, but the endpoints expect the id value exactly as the API returns it, and a UUID is not accepted. Pass the returned id through unchanged when reading, updating, or deleting a skill. Only the documentation changed — the endpoints have always behaved this way. The page also now states the request budget of 1000 requests per hour, and that listing skills returns one complete list rather than a page, so there is no cursor to follow.

Added Agent Configuration Versions, a new reference page for reading the configuration history of a phone number. List every configuration the number has served, newest first, and read any one of them by id. Read the configuration the number serves now from the active path. A number that has not moved to versioned configuration lists nothing and has no active version.

Added a method to Agent Configuration Versions that sets the configuration a phone number serves. Deploying a new configuration, rolling back to an earlier one, and cloning one from another phone number of the same WhatsApp Business Account are all the same request. Label the move a deploy or a clone with reason. Without it, the server records a move back to a configuration the number served before as a rollback, and any other move as a clone. Send expected_active_version_id to make the change conditional on the configuration you believe is active.

Added a 409 Conflict response to the write operations on Agent instructions and skills. A request gets this response when another write changes the same phone number at the same time. Nothing is saved when it happens, so retry the request as it was sent.

Added the Business Agent Usage Insights API reference. Use it to get billable messages, billed tokens, and charges for your Meta Business Agent account over a date range, by hour, day, or month.

Updated End-to-end setup: the Thread Control (Cloud API) response for release and take now includes a request_id next to messaging_product. Include it when you contact support about a specific call.

Corrected the documented format of the entry_id path parameter on Agent Allowlist. The reference page showed a plain numeric example for entry_id and for the id field returned when an entry is added or listed, but the endpoint expects the id value exactly as the API returns it. Pass that value through unchanged when removing an entry. Only the documentation changed — the endpoint has always behaved this way.

Updated Agent Event so a failed event names why it was not delivered. The error_message field previously returned internal_server_error for every failure, including expected ones you can act on. It now returns consumer_not_in_agent_audience, agent_not_enabled, thread_not_owned_by_agent, event_content_rejected, billing_not_configured, or agent_temporarily_unavailable where one of those applies, and keeps internal_server_error for anything else. For example, an event addressed to a consumer who is not on your allowlist while ai_audience is ALLOWLISTED_ONLY now returns consumer_not_in_agent_audience.

Corrected the documented format of the product_id path parameter on Agent Knowledge Catalog. The reference page showed a plain numeric example for product_id and for the id field returned when an entry is created or listed, but the endpoints expect the id value exactly as the API returns it. Pass that value through unchanged when reading, updating, or deleting a catalog product entry. Only the documentation changed — the endpoints have always behaved this way. These endpoints remain deprecated; new integrations should use Commerce Manager. The page also now states the request budget of 1000 requests per hour.

Corrected the documented format of the website_id path parameter on Agent Knowledge Websites. The reference page showed a plain numeric example for website_id and for the id field returned when a crawl entry is created or listed, but the endpoints expect the id value exactly as the API returns it. Pass that value through unchanged when reading, updating, or deleting a website crawl entry. Only the documentation changed — the endpoints have always behaved this way. The page also now states the request budget of 1000 requests per hour.

Corrected the documented format of the faq_id path parameter on Agent Knowledge FAQs. The reference page showed a plain numeric example for faq_id and for the id field returned when an entry is created or listed, but the endpoints expect the id value exactly as the API returns it. Pass that value through unchanged when reading, updating, or deleting an FAQ entry. Only the documentation changed — the endpoints have always behaved this way. The page also now states the request budget of 1000 requests per hour.

Corrected the documented format of the file_id path parameter on Agent Knowledge Files. The reference page showed a plain numeric example for file_id and for the id field returned when a file is uploaded or listed, but the endpoints expect the id value exactly as the API returns it. Pass that value through unchanged when reading or deleting a file. Only the documentation changed — the endpoints have always behaved this way. The page also now states the request budget of 1000 requests per hour.

Corrected the documented format of the tool_id and connector_id path parameters on Connector Tools. The reference page showed plain numeric examples for both, and for the id field returned when a tool is created or listed, but the endpoints expect the id value exactly as the API returns it. Pass that value through unchanged when reading, updating, deleting, or running a tool. Only the documentation changed — the endpoints have always behaved this way. The page also now states the request budget of 1000 requests per hour.

Added Meta Business Agent support, a page describing how to reach support. It covers opening a Direct Support ticket as an enterprise developer, selecting the right business account, and including the WhatsApp Business phone number ID — without which most issues cannot be investigated, since agent configuration, connectors, and conversation history are all scoped to that number. End clients of a Tech Provider or Solution Partner should contact their provider instead. All developers can ask a question on the Meta Developer Community Forum.

Added Catalog integration and real-time inventory checks, a use case guide for the availability layer beneath the other commerce guides. The guide covers what belongs in a Meta product catalog versus what has to be read live, linking the catalog in Commerce Manager, a resolve_location and check_stock connector tool pair for stock that varies by location, and the catalog-to-inventory drift modes that fail silently. The agent_config/catalog endpoint is deprecated; new integrations should use Commerce Manager.

Added Smart product recommendations, a use case guide for the case where a shopper describes a need rather than naming a product. The guide covers the catalog fields that determine match quality, a batched availability tool that returns only sellable products, and presenting the results as a carousel the shopper can select from.

Added User login, a use case guide for managing the signed-in session in a conversation. The guide covers starting as a guest, upgrading to a known customer, keeping the session alive, and ending it cleanly so nothing leaks between people who share a phone number.

Added Customer OTP authentication, a use case guide for verifying a customer’s identity inside a conversation with a one-time passcode issued by your own system. The guide covers the connector user-auth configuration, the request_passcode, verify_passcode, and refresh tools, marking downstream tools as requiring authentication, and the security rules that keep the exchange from leaking whether an identifier exists.

Added Test your agent, a guide to testing a Meta Business Agent before and after it reaches customers. It covers choosing between the Agent Test API, Agent Eval, and allowlisted live conversations; reading handoff_reason, no_response_reason, quick_replies, and product_variant_ids on a test response; inspecting the LLM_CALL and TOOL_CALL steps behind a turn with Conversation Turns; submitting and polling scored eval runs; and monitoring tool health after launch. A Try to break it section covers adversarial testing — unanswerable and out-of-scope questions, conflicting instructions and never_say_phrases, connector timeouts and empty results, unexpected input, long conversations, and deliberately tripping the rate, allowlist, and budget limits.

Added a Configure handoff section to Booking and reservation agent. The guide’s vehicle-rentals skill routes billing disputes, damage claims, and accidents to your team, but never covered how to make that route exist. The new section pairs the handoff policy on Agent settings with the transfer itself through Thread control (Cloud API), including passing control back when the case is closed.

Documented the rate limits on Agent Test. Requests are limited to 500 per hour for each entity_id, and to 10,000 per hour for each app on the endpoint. Exceeding either limit returns 429 Too Many Requests.

Documented the capacity and rate limits on Agent Allowlist. A WhatsApp business phone number can hold up to 20 allowlisted consumer phone numbers, and an Instagram business account can hold up to 20 allowlisted Instagram accounts; the two limits are counted separately. Adding an entry to a full allowlist returns 400 Bad Request, with the current maximum in the error detail. Adding, listing, and removing entries are each rate limited to 1,000 requests per hour for each app.

Updated Agent Eval responses to include an optional scenario_version field for each evaluation case. Use it to distinguish cases retained from different published scenario suites; older cases return null.

Updated Booking and reservation agent from a connector-integration guide into a use-case enablement guide. New sections cover identifying the renter (WHATSAPP_PHONE_NUMBER baseline, verification scoping, user_auth_required), coordinate-aware search_vehicles with semantic-search guidance, visual components (vehicle carousels, date-capture flows, checkout links), modify_reservation and cancel_reservation tools, checkout-link booking completion with regional payment guidance, post-booking tracking and follow-up, and production hardening (backend idempotency, async confirmation, Insights measurement). Every section that describes an API operation now carries a runnable request example, including the request_definition envelope, a verify_renter_code tool, the vehicle carousel and date-capture UI skills, the cta_url checkout link, an add-on lookup, and a per-tool connector log query.

The Single purchase transaction agent guide is now Multi-component single transaction agent, and covers selling several components in one transaction. The example is a trip made of a flight, a hotel, and a car hire, searched for one date range, priced as a set, and committed as a single booking. The page address is unchanged.

The guide is now scoped to the part of that flow that is specific to a multi-component sale, rather than repeating the agent setup shared by every use case. It covers three connector tools: search_trip_options returns options for every component, price_trip returns one total plus a quote id, and book_trip commits the whole quote in a single write. It also explains why the total must come from the quote tool rather than being added up by the agent, why the booking call should be idempotent on the quote id, and how to handle a component that becomes unavailable between quoting and booking. For agent instructions, knowledge, and connector setup, the guide links to the reference pages and to a full end-to-end walkthrough.

Use this guide when the components are chosen once and only make sense together. For a single dated reservation, see Booking and reservation agent.

Agent skills are now called agent instructions, and UI skills are now called interactive messages, throughout the Meta Business Agent documentation.

This is a naming change only. Nothing about the API has changed:

No action is required. Code written against the API keeps working, and no request needs to change.

Added Get API key, a dedicated page for generating the system user access token that authenticates Meta Business Agent Platform API requests. It covers creating the token in Meta Business Suite with both the whatsapp_business_messaging and whatsapp_business_management permissions, the Business Integration System User (BISU) token option for Solution Partners and Tech Providers calling on behalf of a client’s WhatsApp Business account, and the X-API-Version: 2.0.0 header required on every request.

The documentation navigation has also been reorganized. Topics are now grouped under About, Get started, API reference, and Troubleshooting, with the former Use Cases and How-to Guides groups merged into a single How-to guides group under Get started.

Extended the optional catalog_id field on Onboarding to WhatsApp. Pass the catalog you want the agent to sell from when you onboard a WhatsApp Business phone number, and it is linked to the agent and indexed so product questions can be answered from it. The field previously applied only to Instagram and returned 400 Catalog not supported for a WhatsApp phone number. Omit it to leave the phone number’s existing catalog association unchanged. An unknown catalog, or one the caller cannot manage, returns 400 or 403 as it already does for Instagram.

Documented Business-Scoped User ID (BSUID) support in the user_phone_number parameter of Conversation Turns. The parameter already accepted either a digits-only phone number or a BSUID, but only the phone number was described. Use the BSUID for any consumer who has ever adopted a WhatsApp username — their phone number may not be on file for your business, so a phone-number lookup can return Consumer not found even after the consumer deletes the username, while the BSUID resolves for any consumer who has messaged your business. The behavior is unchanged; only the documentation is.

Added the WHATSAPP_PHONE_NUMBER_NATIONAL macro to the parameter binding options on Connector Tools. Bind a parameter to it when your API rejects E.164 numbers and expects the number as a local subscriber would dial it: the country code is removed and the national trunk prefix is kept for regions that use one, so +60123456789 is sent as 0123456789. Regions without a trunk prefix, such as Singapore, are unaffected by the prefix rule and simply lose the country code. The existing WHATSAPP_PHONE_NUMBER macro is unchanged and still sends the full E.164 number.

The Overview has been rewritten. It now leads with what you can do, and pricing has moved to the billing setup step in Get started.

Added a status field to Agent skills. It is returned by every skill create, read, update, and list response, and reports whether the agent is applying the skill: active once the skill has passed the automated content review, pending_review while the review is still running, and blocked if the skill did not pass. A blocked skill is stored and readable but the agent never applies it, most often because the text asks for or refers to sensitive personal information such as a date of birth or a national ID. Edit the skill to remove that content and the review runs again.

Updated the list response for Agent skills so blocked skills are included. Previously a skill that did not pass the automated content review was omitted from the list even though creating it returned 201 Created, which made it look as though the skill had never been saved. Blocked skills now appear in the list with status set to blocked, so you can find them and edit them. This does not change which skills the agent applies.

Added three use case guides, each working through a complete agent configuration for one scenario in one industry:

Each guide covers agent skills, knowledge sources, connector and connector tool configuration, handoff, testing, and connector health monitoring, and notes where the same API applies in other scenarios.

Updated Booking and reservation agent with a Configure handoff section. The guide already told the agent to route billing disputes, damage claims, and accidents to a support team, but did not explain how to make that route exist. The new section covers setting a handoff policy with Agent settings and transferring the conversation with Thread control (Cloud API), including worked take and release calls and what happens outside staffed hours.

Added Customer support agent, a use case guide for running Meta Business Agent as the first responder on a retail support line. It covers answering policy questions from your own documented policies, looking up a shopper’s recent orders without asking for an order number, starting a return, and raising a ticket when a person is needed. The guide also walks through configuring a handoff policy in agent settings and implementing thread control, so escalated conversations reach a colleague in the same WhatsApp thread.

Documented the 404 Not Found response on the create and run operations of Connector Tools. Both already returned 404 when the connector or tool in the path does not exist, but the response was missing from the reference page, so it was easy to miss when writing error handling. The behavior is unchanged — only the documentation is.

Updated Connector Tools to support Instagram business assets for apps with the bizai_ig_enterprise_api_3p_access capability. Approved apps can now create, list, retrieve, update, delete, and run tools for Instagram agents.

Error responses now include an fbtrace_id field identifying the request that failed. The same value is returned in the X-FB-Request-ID response header on every response, including responses with no body, and is exposed to cross-origin callers. Include it when you contact support so the specific call can be located. See Troubleshooting.

Corrected the documented phone number format for the user_phone_number parameter on Conversation Turns and the for field on Thread Control. Send the number as digits only — country code included, with no leading +, spaces, or separators, for example 15551234567. Both pages previously showed the E.164 form +15551234567, which returns a Consumer not found error.

Added an optional message_id field to Conversation Turns. It identifies the customer message that started the turn and matches the ID delivered in the messages webhook, enabling response-to-webhook correlation. Historical turns may omit the field when the identifier is unavailable.

Added Quickstart, the shortest path from an eligible WhatsApp Business phone number to an agent that responds. It covers the minimum needed to get a reply — generate an access token, check eligibility, call Onboarding, then send messages with Agent test, including multi-turn conversations with conversation_id. Billing, app subscriptions, webhook fields, and turning the agent on for WhatsApp users remain in Get started.

Updated Agent Eligibility to allow authorized Instagram Enterprise integrations to access eligibility checks. Existing WhatsApp integrations are unaffected.

Added Writing UI skills, a guide explaining how to write UI skills and the data each component type needs. It covers every supported component_type — cta_url, image, interactive_list, interactive_reply_buttons, location, location_request, carousel_url, carousel_quick_reply, and flow — and lists the data elements you describe in each skill’s free-form instruction.

Updated Agent Settings. Turning your agent on with ai_audience set to ALLOWLISTED_ONLY no longer requires a payment method on your Business Agent account. An allowlisted-only agent responds only to the consumers on your channel allowlist, so you can enable it and test end to end before you set up billing. Turning the agent on for EVERYONE, or expanding an already-enabled allowlisted-only agent to EVERYONE, still requires a payment method and returns a 400 until one is attached.

Updated crawl_status on Website Knowledge to describe the crawl itself rather than what was extracted from it. A site we crawled successfully now reports completed, or the new completed_no_data value when the crawl worked but the site had nothing we could extract. failed is now reserved for crawls that fetched no pages at all. Previously a healthy site with no FAQ or business information page could report failed.

Added a crawl_error field to the same responses. When crawl_status is failed, it carries a readable explanation such as a site being unreachable or blocked by its own robots.txt, so you can tell a site-side problem from one you need to report. It is empty while a crawl is running and for crawls that fetched pages.

Documented that the consumer Allowlist only restricts who the agent responds to when the ai_audience setting is set to ALLOWLISTED_ONLY. The default is EVERYONE, where the agent responds to all consumers and the allowlist is ignored. Get started now covers the required call sequence, and Capabilities notes the dependency.

Added Single purchase transaction agent, a use case guide for configuring an agent that answers course questions and submits enrollment requests over WhatsApp. The guide walks through agent skills, FAQs, syllabus uploads, course catalog crawling, an enrollment connector with availability and enrollment tools, and agent testing, with automation scripts for FAQ sync, syllabus updates, catalog recrawls, and connector health monitoring. Each step also explains how the API applies to other one-time, capacity-limited sales scenarios such as appointment booking, event registration, and travel bookings.

Added Booking and reservation agent, a use case guide for configuring an agent that helps renters choose a vehicle class, check availability for a date range, book a car, and look up an existing reservation over WhatsApp. The guide walks through agent skills, rental policy FAQs, uploading vehicle classes to the catalog knowledge source, crawling help and location pages, a reservations connector, and the search_vehicles, create_reservation, and check_reservation_status connector tools, including binding the renter phone number with the WHATSAPP_PHONE_NUMBER macro. Each step also explains how the API applies to other date-range rental scenarios such as equipment hire and boat rental.

Added Thread Control (Cloud API), a new reference page for transferring control of a consumer conversation. POST /business/whatsapp/phone_numbers/{phone_number_id}/thread_control either releases a thread back to Meta Business Agent as the automatic responder, or takes control from the current owner so your own application can respond. Requires the whatsapp_business_messaging permission.