Meta Business Agent API: The Technical Onboarding Guide for Developers
The easiest way to set up the Meta Business Agent is via the WhatsApp Business app or the Meta Business Suite. However, if you’re a developer or an enterprise organisation and want full control over the agent, to integrate it into existing systems and control it programmatically, you’ll need to use the API. This guide walks you through the technical onboarding process.
This article is part of our comprehensive Meta Business Agent Guide – there you’ll find all the topics relating to the Meta Business Agent at a glance.
Who is this guide for?
This article is aimed at developers and technical teams who wish to set up and manage the Meta Business Agent via the API. A basic understanding of REST APIs, JSON and the WhatsApp Business Platform is required. If you do not have a technical background, you are better off using the app or Business Suite version.
We explain the difference between the two versions here: WhatsApp Business App vs. Meta Business Suite – which one is right for you?
Requirements
Before you begin the API onboarding process, the following prerequisites must be met:
- Meta Developer Account: Registered at developers.facebook.com
- Meta Business Portfolio: A fully set-up Business Portfolio in the Meta Business Suite
- Developer App: An app in the Meta Developer Dashboard containing the necessary products
- WhatsApp Business account: A registered WhatsApp Business account linked to the Business Portfolio
- Verified Business: Your business must be verified in Meta Business Manager
Step 1: Create a system user
The first step is to create a system user in Meta Business Suite. System users are technical accounts used for API access that are not linked to a personal Facebook account. This is important for stability: if an employee leaves the company, API access remains in place.
In the Meta Business Suite, go to Settings, then Users, and select System Users. Create a new system user with the Administrator role. Then assign the necessary assets to this system user: your Developer App and your WhatsApp Business account.
Step 2: Generate an access token
You can now generate an access token using the System User. This token authenticates all API calls. Under System User, click ‘Generate token’, select your developer app and enable the following permissions:
- whatsapp_business_management
- whatsapp_business_messaging
Store the generated token securely. It must be included in the Authorisation header with every API call. Bear in mind the token’s expiry time and implement a refresh mechanism to ensure your integration does not stop unexpectedly.
Step 3: Call the Agent Onboarding API
You can now use the access token to create the agent via the API. The onboarding call is a POST request to the agent endpoint, with the WhatsApp Business phone number ID as a path parameter.
The request body contains the agent’s basic configuration parameters: name, initial instructions and authorisation of the data sources. Meta processes the request and returns an agent ID, which you will need for all subsequent API calls.
We cover the full endpoint documentation, all parameters and example responses in detail in the video course. There you will also find ready-made code snippets for the most common languages.
Step 4: Set up the knowledge base
Once the agent has been initially set up, you populate the Knowledge Base programmatically. The API supports various types of knowledge sources:
Text-based content: FAQs, product descriptions and guidelines in the form of structured text
Documents: PDFs and other documents are submitted via file upload and automatically processed by the agent
Website URLs: You can submit URLs, which the agent automatically crawls and synchronises
Catalogues: Product catalogues from Meta Commerce Manager are linked directly
The order in which you enter these sources, and how you should structure the content so that the agent can access it optimally, is not a trivial matter. If you take an unsystematic approach here, you will end up with an agent that, whilst technically functional, is disappointing in terms of quality.
Step 5: Configure Audience Control and Handoff
The API gives you full control over the agent’s audience control. You can programmatically specify which user groups receive AI responses: all contacts, new contacts only, or only users from specific ad campaigns.
The handoff configuration is also managed via the API. You define trigger topics at which the agent automatically hands over to a human agent. These topics can be keyword-based, intent-based or sentiment-based. A well-defined handoff configuration is one of the most critical aspects of the entire setup.
Anyone using the API in an enterprise context with CRM and tool integrations should also take a look at the overview of the Meta Business Agent Platform – Enterprise solution.
Step 6: Set up webhooks
To ensure full integration, you need to set up webhooks so that Meta can notify your server when relevant events occur. Relevant events include new messages, handoff triggers, agent errors and performance updates.
The webhook endpoint must be publicly accessible, support HTTPS and pass the Meta verification process. During setup, Meta sends a verification token to your endpoint, which you must return before events are delivered.
Step 7: Testing and going live
Before you put the chatbot live, test it systematically via the API. Meta provides a test environment where you can simulate conversations and check the quality of the responses without involving real customers.
A separate chapter in the video course covers what a systematic testing process looks like, which scenarios you absolutely must run through, and how to objectively assess the quality of the responses before going live. If you skip this step, you risk making a poor first impression on real customers.
Day-to-day operations and monitoring
The work isn’t done once the system goes live. A well-run agent is continuously monitored and optimised. The API gives you access to performance metrics: response rates, handover rates, customer satisfaction indicators and error logs.
Schedule regular reviews of the knowledge base, particularly when products, prices or policies change. An agent providing out-of-date information erodes trust more quickly than no agent at all.
Anyone looking not just to get the Meta Business Agent up and running technically, but to build an integration that runs stably in the long term and delivers real business value, will find what they need in the Memacon® Meta Business Agent package – currently in development. The package will contain the full technical documentation: code snippets, test logs and best practices from hundreds of projects. Video courses, guides and everything in one place.
Until then: sign up now for the Memacon® Meta Business Agent newsletter using the button or the QR code below, and don’t miss any updates.
WhatsApp-Newsletter
Regular updates on the
Meta Business Agent
