> This is part 1 of 3 of the full documentation (pages 1–100 of 269).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.360dialog.com/docs/llms-full.txt/1
> Page index: https://docs.360dialog.com/docs/llms.txt
# Overview
Welcome to the 360dialog Documentation Hub, a central resource for everything related to the WhatsApp Business API.
This documentation is designed for developers, solution architects, support agents who work with the WhatsApp Business Platform through 360dialog.
Explore these guides to integrate and optimise WhatsApp messaging workflows with ease.
### Get started
Kick off your WhatsApp Business API journey with quick access to the most essential guides and tools.
Cover image
Sandbox API
Get free & immediate access to our Sandbox environment for WhatsApp.
***
This documentation is continuously updated to reflect platform changes and new features.
# Pricing
Costs associated with 360Dialog & WhatsApp for Business
Each WhatsApp Business channel requires an active subscription to operate. This guide outlines the pricing structures, management workflows, and billing cycles within the 360Dialog Hub.
Each WhatsApp Business channel generates two primary categories of costs:
{% stepper %}
{% step %}
#### 360Dialog Monthly Subscription License Fee
Fixed costs for infrastructure, hosting, and platform access.
{% endstep %}
{% step %}
#### WhatsApp Messaging and Call Fees
Variable usage costs determined by Meta.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
Optional add-ons such as 360Pilot may generate additional charges. These services are invoiced separately from standard license and messaging costs.
{% endhint %}
### Monthly Subscription License Fee
| | | Monthly (EUR) | Monthly (USD) |
| --------------------------------------------------------- | ----------------------------- | -------------------------------------------------- | -------------------------------------------------- |
| Regular Channel Tier | Standard Subscription | 49 EUR | 59 USD |
| Premium Channel Tier | Enhanced Features and Support | 99 EUR | 119 USD |
| Higher Throughput | High-Volume Network Upgrade | 249 EUR | 299 USD |
{% hint style="info" %}
Subscriptions become billable from the moment a channel is activated on the 360Dialog platform.\
From that point, it remains active and billable until manually cancelled.
Subscriptions renew automatically on the 1st day of each month.
For more details, see [Subscriptions](/docs/hub/subscriptions)
{% endhint %}
### WhatsApp Messaging & Call Fees
Usage-based costs are dictated by official Meta Rate Cards. 360Dialog currently supports WhatsApp message pricing in EUR, USD, and INR.
#### 🔗 Official Meta Rate Cards
Meta determines the official pricing for messaging and voice calls. Use the resources below to find specific rates for your region and category:
* [Official Meta Messaging Rate Cards & Volume Tiers](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing#rate-cards-and-volume-tiers)
* [Official Meta Rate Card Updates](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing#updates-to-rate-cards)
#### Billable Messaging (Templates)
Templates are the primary billable message type. Rates are determined by Meta based on:
* Category: Marketing, Utility, or Authentication.
* WABA Timezone: The region configured in the WhatsApp Business Account.
* Monthly Volume: Current volume tiers as defined by Meta.
{% hint style="info" %}
Marketing Message Surcharge: Sending marketing content via the standard `/messages` endpoint instead of the official Marketing Messages API results in a 7% increase over Meta’s standard rates. Utilize the Marketing Messages API with fallback enabled to avoid this.
{% endhint %}
For more, see [Free vs. Billed Messaging](/docs/get-started/pricing/free-vs-billed-messaging)
#### WhatsApp Voice Call Pricing
Voice call pricing is defined by Meta and published in the official Volume-Based Pricing (VBP) Rate Cards for the WhatsApp Business Calling API.
* [Meta Volume-Based Pricing (VBP) Rate Cards for Voice](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/pricing#rate-cards-and-volume-tiers)
Call pricing is determined by the call direction (inbound or outbound), the recipient country prefix code, and the total duration in minutes.
# Free vs Billed Messaging
Under Meta’s price-per-message model, billing is determined by the category of the message and the timing of the interaction. While some messages incur costs, others are free depending on the specific "window" in which they are sent.
{% hint style="info" %}
Free messages do not consume the 360Dialog prepaid credit balance and are excluded from Meta monthly volume tiers or discount calculations.
{% endhint %}
{% hint style="danger" %}
Starting **October 1st, 2026,** Meta will charge on a per-message basis for **all** service messages: Freeform messages, and utility templates sent within an open 24-hour customer service window will no longer be free to send.
{% endhint %}
### Conversation Windows (Meta Rules)
#### Customer Service Window (User-Initiated)
A 24-hour window opens the moment a user sends a message to the business.
| | Sending Window | Billing Status | Examples |
| ----------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | --------------------------------------------- |
| Customer Service | Within 24 hours of user's message | Free | Support replies, order updates, reminders |
| Post-Window | After the 24-hour window expires | Charged (Template required) | Re-engagement, follow-ups |
#### Free Entry Point Window (Ads & Page CTAs)
A 72-hour free window opens when a user initiates a chat via a Click-to-WhatsApp Ad or a "Message" CTA on a Facebook/Instagram Page.
| | Sending Window | Billing Status | Examples |
| ----------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | --------------------------------------------- |
| Free Entry Point | Within 72 hours of Ad/CTA click | Free | Chats from ads, "Message Us" buttons |
| Post-Window | After the 72-hour window expires | Charged | Continuation of the conversation |
### Billable vs. Non-Billable Messages
#### Billable Messages
Template messages are the only billable messages on the platform. Billing follows the category assigned by Meta during approval.
| | Free | Charged | Examples |
| --------------------------------------------------- | ----------------------------------------- | -------------------------------------------- | --------------------------------------------- |
| Marketing | Inside Free Entry Point Window | Outside Free Entry Point | Promotions, re-engagement |
| Utility | Inside Service or Free Entry Window | Outside both windows | Payment/Delivery confirmations |
| Authentication | Inside Free Entry Point Window | Outside Free Entry Point | OTPs, password resets |
#### Non-Billable Messages
Free-form messages (Text, Images, PDFs, etc.) are always free but are blocked outside of an active Customer Service or Free Entry Point Window.
For more, see [Templates](https://docs.360dialog.com/docs/hub/template-management-ui) & [Messaging Rules](https://docs.360dialog.com/docs/messaging/overview)
### Volume Tiers & Aggregation
Lower rates for Utility and Authentication templates are unlocked based on monthly volume.
| | Monthly Charged Messages | Discount |
| --------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------- |
| Tier 1 | 0 – 100,000 | N/A |
| Tier 2-6 | 100,001+ | 5% to 25% off |
Key Tiering Rules:
* Volumes are aggregated across all WABAs in your Business Portfolio
* Only messages that incur a fee count toward tiers
* Counts reset to zero at 12:00 AM on the 1st of every month (WABA timezone)
For more, see [Meta Volume Tiers](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing#volume-tiers)
### Pricing Accuracy and Updates
Pricing is subject to updates from Meta or 360Dialog. For the most accurate information:
* Monitor the 360Dialog Hub for usage and balance information
* Read updates and notifications sent to emails associated with the 360Dialog Hub
* Reach out to Support for personalized guidance
* Consult official Meta Rate Cards for regional changes
For more, see [Meta Pricing Updates](https://developers.facebook.com/docs/whatsapp/pricing/updates-to-pricing)
# Higher Throughput
Higher thoughput messaging capabilities and costs
The Higher Throughput Tier is designed for businesses that require message throughput beyond Meta’s standard limits. By migrating to a high-performance infrastructure, 360Dialog enables delivery rates of up to 1,000 messages per second, ensuring time-sensitive campaigns and critical notifications reach users without delay.
{% hint style="info" %}
By default, WhatsApp channels operate at Meta’s standard throughput of up to 80 messages per second.
{% endhint %}
### Pricing Breakdown
The total price includes the Premium Tiersubscription and a higher-throughput network upgrade.
| | Monthly (EUR) | Monthly (USD) | Throughput |
| ------------------------------------------------------ | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------- |
| Higher Throughput | 249 | 299 | 1000 msg/sec |
If multiple channels require higher throughput capabilities, each channel will be upgraded individually, and corresponding fees will be applied per channel.
#### Eligibility
To qualify for Higher Throughput, the channel must meet the following requirements:
* [x] Registered on the WhatsApp Cloud API
* [x] Maintain a quality rating of Medium or higher
* [x] Be able to initiate conversations with an unlimited number of unique customers within a rolling 24-hour period
{% hint style="info" %}
To reach unlimited conversations with unique customers:
* Initiate conversations with at least 50,000 unique customers within a rolling 7-day period
* Wait 24 hours after reaching this milestone before the upgrade becomes available
* Receive approval from Meta for unlimited conversations
For more information, see the [Messaging Limits and Quality Rating](/docs/resources/wabas/messaging-limits)
{% endhint %}
#### Request Higher Throughput
{% stepper %}
{% step %}
Confirm the channel meets the eligibility requirements
{% endstep %}
{% step %}
Contact [Support ](/docs/support/get-support)and provide the following information:
* Channel to be upgraded
* Client Hub account ID
* Average daily conversation volumes and quality rating
{% endstep %}
{% step %}
Once approved, the channel will be migrated to the higher-throughput network and billing will be updated accordingly
{% endstep %}
{% endstepper %}
#### Remove
To revert a channel to standard throughput (80 messages per second), please contact Support. Upon request, the channel will be moved back to the Regular or Premium tier, and the corresponding billing adjustments will take effect at the start of the next billing cycle.
# Payments
This page explains how to manage payment in the 360Dialog Hub.
To avoid service interruptions, a valid payment method must be added during the 360Dialog Hub creation process as part of onboarding.
{% hint style="info" %}
During onboarding a temporary authorisation may be placed on the payment method provided.
This authorisation of funds:
* Reserves a specific amount on the card or selected payment method
* Is not a charge
* Does not transfer funds
* Automatically releases funds if not captured
If there are delays in the release of authorised funds, contact the banking partner directly.
Release timelines are determined by the issuing bank.
{% endhint %}
### Payment Methods
Credit / Debit cards are the primary supported payment method in the 360Dialog Hub.
The following card types are supported:
* Visa
* Mastercard
* American Express (AMEX)
A payment processing fee applies to Licence Fee invoices.
| | Supported | Processing Fee |
| -------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------- |
| Credit / Debit Card | Yes | 4% |
### Payment Failures
Payment failures may occur for several reasons, including:
* Expired card
* Insufficient funds
* Card spending limits
* 3D Secure authentication issues
To reduce the risk of service interruption:
* [x] Keep card details up to date
* [x] Monitor card balances regularly
* [x] Contact the bank if payment failures occur without a clear reason
### Service Suspensions
If payment attempts fail, services may be suspended and a notification will be sent to the billing email configured in the Hub.
Outbound messaging and onboarding of new channels may be blocked when billing obligations remain unpaid.
Service access is automatically restored once the outstanding payment has been successfully processed.
For more on managing payments, see [Billing](/docs/hub/billing)
# Sandbox
Learn how to get started with 360Dialog Sandbox API
We provide a developer-friendly test environment for anyone who wants to explore the usage of our WhatsApp API. You can test sending messages and templates in the test environment.
**Sandbox Base Path:** `https://waba-sandbox.360dialog.io/`
Each test account has its own API key and one fixed recipient, either your phone number or your business-scoped user ID. You can only send test messages to that recipient. If you want to message more than one number, set up a WhatsApp Business Account instead of using the sandbox.
## Limitations
### **What you can do with the sandbox**
* You can use the sandbox API key to send freeform messages and templates to your own phone number (or your own business-scoped user ID if your phone number was not shared).
* A maximum of 200 messages can be sent with the sandbox. Every request that reaches the messaging API counts towards this limit, even if the message itself is rejected. Once the limit is reached, requests fail with HTTP 429.
* Your phone number acts like a user and can send and receive messages.
* The number can be a landline number, as long it is able to use WhatsApp.
* You can change your webhook URL at any time.
* Each Sandbox API key is linked to one fixed recipient (either your phone number or your business-scoped user ID) and you can only send test messages to that recipient. If you wish to send messages to more than just your recipient, then we recommend setting up a WhatsApp Business Account to use instead of the sandbox.
### **What you can't do with the sandbox**
* The Sandbox is a test environment only. Messages and templates can be sent only to your own phone number, or to your own business-scoped user ID if your phone number was not shared.
* You can send only predefined templates available in the sandbox: `disclaimer`, `first_welcome_messsage`, and `interactive_template_sandbox`. *(Note: Template inventory requires confirmation with the Partner APIs team).*
* Uploading and retrieving media files using the media ID.
## How to get started with sandbox
{% stepper %}
{% step %}
### **Get an API Key**
You can get an API key by sending a message on WhatsApp to phone number `+551146733492` with the content **`START`** (**`START`** must be in all UPPERCASE). You can quickly send the message by:
* Clicking this link:
* Or scanning this QR code on your phone:
You will later receive a response containing your API key. This API key needs to be used when making API requests.
### If your phone number is not shared
If your phone number is not shared when sending the **START** message, WhatsApp will trigger a contact-request message template (`request_contact_info_en`) on your device prompting you to share your contact info.
If your phone number is not shared or is delayed, you will receive an API key after a timeout (within 5 minutes). The exact message you receive will be:
> `Your new api-key is: "". Your business-scoped user id is: "". Because your phone number was not shared, send messages using the "recipient" field set to your business-scoped user id instead of "to".`
> **Business-scoped user ID (BSUID)**: an identifier WhatsApp assigns to a user for one specific business. WhatsApp sends it instead of the phone number when the user's number is not shared with the business.
>
> Accounts created in this manner are identified by BSUID only, do not have a registered phone number associated, and must use the `recipient` field instead of `to` when sending API requests.
> {% endstep %}
{% step %}
### **Set the Sandbox Webhook URL**
`POST` `https://waba-sandbox.360dialog.io/v1/configs/webhook`
Setting a webhook URL is necessary for receiving messages (and message status updates). Any message you send to `+551146733492` will be forwarded to the webhook URL you set.
You can use an external service (such as [requestbin.com](https://pipedream.com/requestbin) or [webhook.site](https://webhook.site/)) to create a temporary webhook URL. You can also use an external service such as ngrok to tunnel a port from localhost to a temporary public URL.
{% hint style="warning" %}
**Important: HTTPS is mandatory.** A non-HTTPS URL will be rejected with HTTP 400: `"url must be HTTPS"`. When picking a URL from webhook.site, requestbin, or ngrok, you must select the secure `https://` variant.
{% endhint %}
The API key you received in the previous step needs to be passed in the **D360-API-KEY** header.
**Request Example**
```shellscript
curl --request POST \
--url https://waba-sandbox.360dialog.io/v1/configs/webhook \
--header 'Content-Type: application/json' \
--header 'D360-API-KEY: YOUR_API_KEY' \
--data '{"url": "https://your-webhook-adress"}'
```
**Headers**
| Name | Value |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |
| `D360-API-KEY` | Your API key |
**Request Body**
| Name | Type | Value |
| ----- | ------ | ---------------- |
| `url` | string | Your webhook URL |
{% tabs %}
{% tab title="200 Webhook URL Set" %}
```json
{
"url": "https://example-webhook-url"
}
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
### **Send a Message to the Sandbox**
Send a message to the number `+551146733492` again. You will receive an Inbound Message event on your webhook. This webhook event contains the phone number that sent the message, along with the message's contents. An example of it can be seen below.
The webhook is not just used for receiving messages; it is also used for receiving status updates on your outbound messages. After you send a message via the API, you will receive a webhook event when the message is sent/delivered to your recipient, and when your recipient has read the message.
{% endstep %}
{% step %}
### Inbound Message Event
{% tabs %}
{% tab title="Phone Number Account" %}
```json
{
"entry": [
{
"changes": [
{
"field": "messages",
"value": {
"contacts": [
{
"profile": {
"name": "USER_NAME"
},
"wa_id": "PHONE_NUMBER"
}
],
"messages": [
{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "1591955533",
"type": "text",
"text": {
"body": "MESSAGE_BODY"
}
}
]
}
}
]
}
]
}
```
{% endtab %}
{% tab title="Business-scoped User ID (BSUID) Account" %}
```json
{
"entry": [
{
"changes": [
{
"field": "messages",
"value": {
"contacts": [
{
"profile": {
"name": "USER_NAME"
},
"user_id": "YOUR_BUSINESS_SCOPED_USER_ID"
}
],
"messages": [
{
"from_user_id": "YOUR_BUSINESS_SCOPED_USER_ID",
"id": "wamid.ID",
"timestamp": "1591955533",
"type": "text",
"text": {
"body": "MESSAGE_BODY"
}
}
]
}
}
]
}
]
}
```
{% endtab %}
{% endtabs %}
### Message Status Event
{% tabs %}
{% tab title="Phone Number Account" %}
```json
{
"entry": [
{
"changes": [
{
"field": "messages",
"value": {
"statuses": [
{
"id": "wamid.ID",
"recipient_id": "PHONE_NUMBER",
"status": "read",
"timestamp": "1591955668"
}
]
}
}
]
}
]
}
```
{% endtab %}
{% tab title="Business-scoped User ID (BSUID) Account" %}
```json
{
"entry": [
{
"changes": [
{
"field": "messages",
"value": {
"statuses": [
{
"id": "wamid.ID",
"recipient_user_id": "YOUR_BUSINESS_SCOPED_USER_ID",
"status": "read",
"timestamp": "1591955668"
}
]
}
}
]
}
]
}
```
{% endtab %}
{% endtabs %}
If your phone number is not shared, webhook events identify you by your business-scoped user ID instead of your phone number:
* Inbound messages carry `from_user_id` (and `contacts[].user_id`) instead of `from` / `wa_id`.
* Status events carry `recipient_user_id` instead of `recipient_id`.
*
{% endstep %}
{% step %}
### **Respond using the Sandbox API**
**Send response message**
`POST` `https://waba-sandbox.360dialog.io/v1/messages`
You can send a response message (or a message template) to the phone WhatsApp number with the above request URL and the body parameters as described below.
**Request Example**
```shellscript
curl --request POST \
--url https://waba-sandbox.360dialog.io/v1/messages \
--header 'Content-Type: application/json' \
--header 'D360-API-KEY: YOUR_API_KEY' \
--data '{"messaging_product": "whatsapp", "to":"YOUR_PHONE_NUMBER","type":"text","text":{"body":"Hello world"}}'
```
**Headers**
| Name | Value |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |
| `D360-API-KEY` | Your API key |
**Request Body**
Name
Description
Key
recipient_type
string
Set to individual
to
number
Set to your phone number
type
string
Set to text
text
object
Contains a body string field, which is where your message should go (e.g. "body": "Hello world")
messaging_product
string
Mandatory payload that should be set to whatsapp
{% hint style="warning" %}
**Important Configuration Note:**
Send either `to` or `recipient`, matching how your test account was created. `to` must be exactly the phone number your API key is tied to, and `recipient` must be exactly the business-scoped user ID your API key is tied to. Any other value is rejected with HTTP 403.
{% endhint %}
#### Example Request Payload
{% tabs %}
{% tab title="Example Request Payload " %}
```json
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "",
"type": "text",
"text": {
"body": "Hello world"
}
}
```
{% endtab %}
{% tab title="Business-scoped User ID (BSUID) Payload" %}
```json
{
"messaging_product": "whatsapp",
"recipient": "",
"type": "text",
"text": {
"body": "Hello world"
}
```
{% endtab %}
{% endtabs %}
#### Response (201 Created)
```
{
"messages": [
{
"id": "message_id"
}
],
"meta": {
"api_status": "stable",
"version": "2.31.5"
}
}
```
#### Error Reference
| Status | Meaning |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **401** | Missing or invalid `D360-API-KEY` header. |
| **403** | The `to` or `recipient` value does not match the recipient your API key is tied to, or the request contains neither field. |
| **429** | You have used up the 200 message limit of the sandbox. |
| **502** | The message could not be delivered to the messaging API. Try again later. |
| **504** | Timeout while delivering the message. Try again later. |
| {% endstep %} | |
{% step %}
### **Send a Template Message (optional)**
`POST` `https://waba-sandbox.360dialog.io/v1/messages`
There are 3 templates available to test in the sandbox. There is no possibility to add or edit templates; you must use one of the predefined templates listed below.\
\
**Available templates are:**
* `disclaimer`\
Using this template will just send a regular text message, which can’t be edited.
* `first_welcome_messsage`\
This is an example of a template with a personalization possibility (you can personalize the receiver's name).
* `interactive_template_sandbox`\
This template contains 2 buttons for which you can pass customer URLs.
**Request Example**
```bash
curl --request POST \
--url https://waba-sandbox.360dialog.io/v1/messages \
--header 'Content-Type: application/json' \
--header 'D360-API-KEY: YOUR_API_KEY' \
--data '{"to": "YOUR_PHONE_NUMBER", "messaging_product": "whatsapp", "type": "template", "template": { "name": "first_welcome_messsage", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Placeholder 1"}'
```
**Headers**
| Name | Value |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |
| `D360-API-KEY` | Your API key |
**Request Body**
If the request is valid, you will receive an HTTP 201 success response.
{% tabs %}
{% tab title="201: Created " %}
```json
{
"messages": [
{
"id": "message_id"
}
],
"meta": {
"api_status": "stable",
"version": "2.35.4"
}
}
```
{% endtab %}
{% endtabs %}
**Example Request Payload**
**`first_welcome_messsage`**
```json
{
"to": "",
"messaging_product": "whatsapp",
"type": "template",
"template": {
"name": "first_welcome_messsage",
"language": {
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Placeholder 1"
}
]
}
]
}
}
```
Note that this example covers `first_welcome_messsage` with personalization. In the case of the `disclaimer` template, the payload is similar but with an empty `components` array (it holds personalization parameters which are not used in `disclaimer`).
If you would like to quickly give the other two templates a try, you can use the JSON body snippets below:
{% tabs %}
{% tab title="'disclaimer' template JSON body" %}
```json
{
"to": "",
"messaging_product": "whatsapp",
"type": "template",
"template": {
"name": "disclaimer",
"language": {
"code": "en"
},
"components": []
}
}
```
{% endtab %}
{% tab title="'interactive\_template\_sandbox' template JSON body" %}
```json
{
"to": "",
"messaging_product": "whatsapp",
"type": "template",
"template": {
"name": "interactive_template_sandbox",
"language": {
"code": "en"
},
"components": [
{
"type": "button",
"sub_type": "quick_reply",
"index": 0,
"parameters": [
{
"type": "payload",
"payload": "aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 1,
"parameters": [
{
"type": "payload",
"payload": "aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
}
]
}
]
}
}
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
{% hint style="info" %}
**Note for Business-Scoped User ID (BSUID) Accounts:**
If your test account is identified by a business-scoped user ID, replace `"to": ""` with `"recipient": ""` in every template payload and API example shown on this page.
{% endhint %}
# About
This page describes the WhatsApp Business Platform and where 360dialog fits into the WhatsApp ecosystem.
## WhatsApp Solutions
WhatsApp offers two dedicated Business Solutions, in addition to the standard WhatsApp Messenger app.
Cover image
WhatsApp Messenger
This is the regular WhatsApp app (also sometimes referred to as the WhatsApp Consumer App) people use every day. It’s designed for personal communication: chatting with friends and family, making calls, sharing photos, and joining group conversations. It is not intended for business operations.
The WhatsApp Business App is built for small businesses. It includes additional features such as a business profile, product catalog, quick replies, labels, and automated greeting messages. Since the introduction of Coexistence, small businesses can message using the Business app and the WhatsApp Business Platform simultaneously. The Business App is sometimes referred to as the SMB app (SMB = Small & Medium Business).
## WhatsApp Business Platform
The **WhatsApp Business Platform** enables businesses to communicate with customers at scale.
360dialog is an official WhatsApp **Business Solutions Provider (BSP)** and Premier Meta Partner.
A WhatsApp BSP is an official partner authorised by WhatsApp to provide businesses with access to the WhatsApp Business Platform. BSPs help businesses set up, manage, and scale WhatsApp messaging.
BSPs like 360dialog have the right to resell usage of our WhatsApp Business Solution by extending a line of credit to businesses. We also host the embedded signup, which is used for client onboarding.
We work with an extensive network of Partner **Tech Providers**, who provide messaging solutions for WhatsApp. Tech Providers have access to the same technical capabilities as Solution Partners (BSPs), but differ in billing and partner status.
## Core APIs & capabilities
#### WhatsApp Cloud API
WhatsApp Cloud API enables businesses to programmatically message and call on WhatsApp. Businesses can use Cloud API to send users a variety of messages, from simple text messages to rich media and interactive messages.
WhatsApp Cloud API includes:
* [**Messaging**](/docs/messaging/overview)**:** Send text messages, rich media, and interactive messages
* [**Calling**](/docs/messaging/calling)**:** Make and receive calls to customers
* [**Groups**](/docs/messaging/groups)**:** Create, manage, and message WhatsApp group conversations
WhatsApp messaging provides a powerful and private way to engage with customers. Use Cloud API to:
* Send order confirmations and shipping updates
* Share appointment availability and other reminders
* Drive upsell and cross-sell opportunities
* Facilitate end-to-end transactions, from product discovery to payment
* Enable multi-factor authentication or one-time passwords to verify accounts and users
* Deliver custom interactive conversational experiences
#### Business Management API / 360dialog Hub
The WhatsApp Business Management API allows you to manage WhatsApp Business Accounts (WABAs) and their associated assets. We provide access to this functionality through the 360dialog Hub for Clients, and through the 360dialog Partner Hub and Partner API for Partners.
To access the Partner API and programmatically manage multiple Clients’ WABAs, you must register as a 360dialog Partner.
Manage account assets with the 360dialog Hub like:
* [**Phone numbers**](/docs/resources/phone-numbers)**:** Add and remove business phone numbers
* [**Templates**](/docs/hub/template-management-ui)**:** Create and modify message templates for scalable messaging.
The 360dialog Hub also gives you access to account analytics like:
* [**Messaging & Pricing analytics**](/docs/hub/insights)**:** The number and type of messages sent and delivered and granular pricing breakdowns for delivered messages.
#### Marketing Messages API for WhatsApp
MM API for WhatsApp is an API for sending optimized marketing messages on WhatsApp.When you send marketing messages through the MM API for WhatsApp, businesses can access new features not available on Cloud API and get automatic optimizations, so high engagement messages can reach more customers.The MM API for WhatsApp includes:
* **Quality-based delivery:** Up to 9% higher marketing message deliveries over Cloud API for high engagement content.
* **Automated creative optimizations:** Automatic enhancements to marketing creative to increase message performance.
* **Performance benchmarks and recommendations:** Comparison of read and click rates versus similar templates from businesses in your region.
* **Conversion metrics:** Measure marketing messages that lead users to perform app events such as ‘Add to Cart’, ‘Checkout Initiated’, or ‘Purchase’.
#### Webhooks
Webhooks deliver JSON payloads to your server for message status updates, incoming messages, asynchronous error handling, and many other notification utilities.The platform relies heavily on webhooks, as the contents of any message sent from a WhatsApp user to your business phone number is communicated via webhook, and all outgoing message delivery status updates are reported via webhook.
# Alphas and Betas
Alphas and Betas are programs run by 360Dialog in collaboration with partners to test new features before they become generally available on WhatsApp for Business APIs.
## About Alphas & Betas
By joining an **Alpha or Beta program**, you gain **early access to WhatsApp features** and the opportunity to provide **feedback that shapes development**.
Your insights are shared with **360Dialog** **and Meta’s product teams**, helping improve products before General Availability (GA).
Alpha and Beta refers to different stages of a product development, being:
* **Alpha** → early-stage, limited functionality, small test group.
* **Beta** → broader testing, more stable, includes improvements from Alpha.
* After Beta → feature becomes GA (General Availability) and is released to all users.
{% hint style="info" %}
Team's notes:
* We **validate and test all features internally** before opening them up for client testing, ensuring a secure and reliable experience.
* Participation requires commitment: active testing and consistent feedback.
{% endhint %}
### Why join?
* [x] **Early Access** — test features before the market.
* [x] **Influence** — your feedback guides product design.
* [x] **Competitive Advantage** — adopt powerful solutions early.
* [x] **Learning** — hands-on with cutting-edge tools.
### Roles & Expectations
When you join a Beta you can expect 360Dialog's
| What we expect from you | What you can expect from us |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
Active usage
|
Support & guidance
|
|
Provide feedback
|
Resources & documentation
|
|
Report issues
|
Progress tracking
|
|
Share learnings
|
Direct collaboration with Meta
|
### How to provide feedback on a feature
* Fill out surveys we share during testing.
* Join scheduled calls or workshops.
* Report issues via email or tickets with clear reproduction steps.
### Best practices for participants
* Test features in **real business scenarios**.
* Explore edge cases (different templates, flows, languages).
* Share both **positive outcomes** and **challenges**.
## Available Programs
## FAQ
* **Do I pay extra to test Alpha/Beta features?**\
No. You pay only for conversations as usual, but must be a 360Dialog client.
* **Does testing impact my current Cloud API setup?**\
No. Tests run in a separate environment.
* **Do you have a public Postman collection for all current running Betas?** \
Yes! You can access using the following link:
{% embed url="" %}
# 360Dialog MCP
Learn how to manage your 360Dialog account using an AI agent
Connect your AI agent to 360Dialog's [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) server and manage WhatsApp infrastructure with ease.
## Introduction
360Dialog MCP is a hosted server that gives AI agents secure and grained access to the 360Dialog Hub public API. It is designed to work with popular AI assistants like Claude, Claude Code, Cursor, Codex, VS Code, and more.
### Benefits
* **Ease of access —** Effortlessly manage assets using natural language
* **AI-powered flows —** Offload existing manual account management flows to AI agents
* **Fine-grained access control —** Select which scopes to allow during connection
* **Optimized for AI —** Tool results are efficiently formatted for best inference performance
* **UI/JSON previews —** See a visual preview of your templates via [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview), and get an example JSON body for sending a template via 360Dialog Messaging API
### Capabilities
* **Search documentation —** Search the public 360Dialog client and partner documentation for troubleshooting, or for implementation reference
* **Manage accounts, users and channels —** List accounts, users, and channels; surface any issues with channels that might block messaging
* **Inspect and edit channel profiles —** Inspect and modify a channel's WhatsApp profile, or submit a new display name
* **Manage WhatsApp templates —** Create, preview, list, and delete WhatsApp templates; get example JSON body for sending a template via 360Dialog Messaging API
* **Configure webhooks —** Read and set webhook configuration per channel, then test webhook URL for issues
* **Query balance and invoices —** See account invoices, channel balance, and balance usage stats
## Quickstart
{% stepper %}
{% step %}
### Connect to MCP
360Dialog MCP is a streamable HTTP server. Any AI tool that has an MCP client, supports the streamable HTTP protocol, and remote MCP servers can connect to it by adding the server's URL:
```shellscript
https://mcp.360dialog.com/mcp
```
**Claude Code** users can run this command to connect to the MCP server:
```shellscript
claude mcp add --transport http 360dialog https://mcp.360dialog.com/mcp
```
**Codex** users can run this command to connect to the MCP server:
{% code overflow="wrap" %}
```shellscript
codex mcp add 360dialog --url https://mcp.360dialog.com/mcp
```
{% endcode %}
You may need to restart the AI tool afterwards for the changes to take effect.
{% endstep %}
{% step %}
### Start Authentication
After adding the MCP server and restarting your MCP client, you will be either:
1. Taken to the 360Dialog MCP consent page, or
2. Be asked by your AI tool to authenticate with the MCP server.
Steps to start or re-attempt authentication with the MCP server vary.
For **Claude Code,** use the `/mcp` command to list your MCP servers. Select **`360dialog`** from the list, and select **`Authenticate`**.
For **Codex,** use the following command to log in:
{% code overflow="wrap" %}
```shellscript
codex mcp login 360dialog
```
{% endcode %}
{% endstep %}
{% step %}
### Authorize Scopes
Before the log in screen, you will be asked to review the access request and pick scopes you want to grant.
Inspect the redirect URL and ensure it is a link you trust. If it is an untrusted link (e.g. unknown non-localhost URL), click **Decline.** Otherwise, select which scopes you would like to grant:
Denying scopes will hide corresponding tools from the AI agent. If `write:channels` is denied, the AI agent will not be shown the `set_display_name` tool.
After selecting/deselecting scopes, click **Approve.**
{% endstep %}
{% step %}
### Log In
Log into your account via email and password, or with Google or Facebook:
If you have access to multiple accounts under the same login, you may be prompted to select an organization. Select the organization you would like to manage to continue.
{% endstep %}
{% step %}
### Test the MCP
Use this example prompt in Claude, Cursor, or your own agent once the server is connected to ensure the connection works:
{% code overflow="wrap" %}
```
List my channels in 360Dialog, and tell me whether the webhook is configured for the first channel.
```
{% endcode %}
Typical tool flow will be:
1. `get_self` — Get identity and account context
2. `list_channels` — Discover available channels
3. `get_webhook` — Read live webhook configuration
If the tools do not work, attempt to reconnect to the 360Dialog MCP.
You may now start integrating AI agents into your WhatsApp Business Account management flows.
{% endstep %}
{% endstepper %}
# Meta Business Agent
Meta Business Agent (MBA) is Meta's enterprise AI agent that talks to your customers on WhatsApp in your brand's voice. Once enabled, it becomes the **primary responder** on a WhatsApp phone number — it answers questions from the knowledge you give it, can take actions in your own systems through connectors, and hands off to your app or a human when needed.
With 360dialog you set up, configure, and run Meta Business Agent through the WhatsApp Business API you already use. This guide walks you through the whole journey, from checking eligibility to a full rollout, and flags the rough edges we found while testing so you don't hit them by surprise.
{% hint style="info" %}
Meta is still shipping fixes and defining parts of the platform (billing, some handoff and file behaviors). Where something is incomplete today, we call it out with a workaround and, where relevant, note that we've raised it with Meta.
**The platform is also still unstable.** Any agent endpoint can intermittently return a 4XX or 500 with no obvious cause. Meta is debugging it; in the meantime, retry the call after a few hours rather than assuming a permanent failure. See Known limitations.
{% endhint %}
## The journey at a glance
Setting up an agent follows six steps. Each has its own page in this guide.
1. [**Check eligibility**](/docs/mba/meta-business-agent/1.-check-eligibility) — confirm the phone number can run MBA.
2. [**Enable and accept terms**](/docs/mba/meta-business-agent/2.-enable-your-agent) — accept the Meta Business AI Terms in Business Manager, add a valid Payment method and then onboard the number.
3. [**Configure your agent**](/docs/mba/meta-business-agent/3.-configure-your-agent) — give it knowledge (business info, FAQs, files, websites), behavior (skills), handoff and follow-up policies, and connectors so it can take actions.
4. [**Test your agent** ](/docs/mba/meta-business-agent/4.-test-your-agent)— try it before customers do.
5. [**Go live with an allowlist**](/docs/mba/meta-business-agent/5.-go-live) — release to a small set of numbers first, then iterate.
6. [**Roll out to everyone**](/docs/mba/meta-business-agent/6.-roll-out-to-everyone) — open the agent to all customers.
Then keep the [**Known limitations & workarounds** ](/docs/mba/meta-business-agent/known-limitations)page handy — it collects every gap in one place.
## Two ways to onboard
You can run Meta Business Agent on 360dialog in two ways, depending on how much control you want. Both are covered in [**Two ways to onboard**](/docs/mba/meta-business-agent/onboarding-options):
* **Via API** — build your own fully custom onboarding and management experience. Available today.
* **MBA Integrated Onboarding** — a hosted, guided flow similar to 360dialog's Number Integrated Onboarding, but for Meta Business Agent.
* **360dialog Hub** — enable and manage MBA directly from the Hub UI, no integration required. Good for a single account that doesn't need programmatic control.
## What you need
* A **WhatsApp Business Account (WABA)** managed on 360dialog (Cloud API), with a phone number that is [eligible for MBA.](/docs/mba/meta-business-agent/1.-check-eligibility)
* Access to **Meta Business Manager** for the WABA's owning business, to accept the Meta Business AI Terms of Service.
* A **payment method** with Meta before opening the agent to `EVERYONE` — today that's a direct credit line, with credit-card support rolling out from **8 September 2026**. Testing under an allowlist (`ALLOWLISTED_ONLY`) doesn't require this — see [Go live.](/docs/mba/meta-business-agent/5.-go-live)
* Your **360dialog API key** (`D360-API-KEY`) for the channel you want to enable.
{% hint style="info" %}
Throughout this guide, example requests use the 360dialog WhatsApp Business API at `https://waba-v2.360dialog.io` with your `D360-API-KEY` header. Your API key already identifies the phone number (entity), so you don't pass a phone number ID in the path. For the exact route and full request/response fields of every endpoint, see the **Meta Business Agent API reference** in this space.
{% endhint %}
# Known limitations
Meta Business Agent is in early access, and we found a number of gaps while testing. This page collects them all in one place so you can plan around them. Each is also flagged inline on the relevant step. We've raised the significant ones with Meta and expect fixes over time — check back for updates.
## Platform stability
| Gap | What to do |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| E**ndpoints intermittently return 4XX or 500 with no obvious cause.** The same request that failed succeeds later with no change on your side. Meta is actively debugging this. | Don't treat a one-off 4XX/500 as a permanent failure or a misconfiguration. Retry the call after a few hours — in every case we've seen, it resolved on its own. If it still fails after a day, contact support. |
## Eligibility & access
| Gap | What to do |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Eligibility check can return **HTTP 500** for a non-eligible or not-yet-enabled number instead of a clean "not eligible." Largely resolved by Meta. | If you see a 500 on `agent_eligibility`, re-check the number really meets the [requirements](/docs/mba/meta-business-agent/1.-check-eligibility) before treating it as an outage. |
| API returns **403** until the **Meta Business AI Terms** are accepted for the WABA. | Accept the terms in Business Manager → WhatsApp Manager → Business AI. Only someone with access to the WABA's **owning** business can accept. See [Enable and accept terms.](/docs/mba/meta-business-agent/2.-enable-your-agent) |
| Availability was **regional** during rollout (Brazil first, EU mid-July 2026). The restriction appears lifted. | If a new-region number reads not-eligible, region may still be the cause — re-check after a short wait. |
| **CORS blocks browser calls** to Meta's agent endpoints. | Call the API from a backend, not directly from a browser. (With 360dialog, keep your `D360-API-KEY` server-side anyway.) |
## Testing
| Gap | What to do |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ~~\*\*`agent_test`\*\*\*\* \*\***only returns replies when the agent is fully published** (`rollout` enabled and `ai_audience = EVERYONE`). Under `ALLOWLISTED_ONLY` it returns an empty response with `no_response_reason = ELIGIBILITY_CHECK_FAILED`. **Raised with Meta; expected to change.**~~ | ~~For pre-launch testing on a production number, use `ALLOWLISTED_ONLY` and message from allowlisted numbers on real WhatsApp. Use `agent_test` on a dedicated test number set to `EVERYONE`. See~~ [~~Test your agent~~](/docs/mba/meta-business-agent/4.-test-your-agent)~~.~~ |
| Each `agent_test` call **starts a fresh conversation** unless you pass back a `conversation_id`; the `to` field is ignored. | Capture `conversation_id` from the first response to continue a multi-turn test. |
## Conversation, handoff & context
| Gap | What to do |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Once the agent **hands off to a human, it stops answering** that chat. | Make sure a human handover path is live before launch — otherwise those customers get no reply. |
| On hand-back, the agent **loses earlier conversation context**. | Don't assume continuity across a human handoff; re-establish context if needed. |
| The handoff notice is the **fixed `message` you define** — it can't be adapted per customer language. | For multilingual audiences, keep the handoff message simple or language-neutral. |
| The agent **doesn't always reply in the customer's language.** | Reinforce language behavior in your skills where it matters. |
| ~~**No API to read who currently holds the conversation** (thread owner) — there's no `GET` for thread control.~~ | You can use [Controlling your Agent](/docs/mba/meta-business-agent/controlling-your-agent#conversation-turns) to follow the turns. |
| **Thread control supports only `release`** (hand back to agent), via the operate endpoint. Your app takes control simply by sending a message. | Use the documented thread-control call to release; see the **API reference**. |
## Files
| Gap | What to do |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `file_name` should include the file extension |
Ensure file\_name is added when uploading files, including the file extension
Example: file\_name="sample.pdf"
|
| **CSV files, and tables inside PDFs, error out** when read. | Put structured/tabular facts into FAQs or business info instead of files. |
| Uploads are `multipart/form-data`, **max 100 MB**. | Keep files within the limit. |
| ~~The agent **can't reliably send files or images out** to customers.~~ | This can be achived now with [UI Skills](/docs/mba/api-ref/ui-skills) |
| ~~**File upload fails when a file name is included.**~~ | ~~Upload without setting a filename in the multipart part.~~ |
## Events
| Gap | What to do |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `agent_event` (proactive outbound) **only works while the agent is on-call** (holds the conversation). Status is poll-only (`request_received → processing → sent/failed/skipped/success`). | Only trigger events when the agent holds the thread; poll for status. |
## Webhooks — the capture gap
| Gap | What to do |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
The agent's conversation travels on the standby field, which Meta delivers only to a single account-wide destination, not your number's webhook. So today you don't receive the agent's live conversation text (consumer inbound + agent replies) on your own webhook.
messages, messaging\_handovers, and bizai delivery statuses do arrive. 360dialog is building routing to deliverstandbyto your webhook.
| The agent's `standby` conversation was previously not delivered to per-number webhooks. **Resolved** — 360dialog now routes `standby` to your number's webhook, re-signed with `x-360dialog-signature`. See [Webhooks](/docs/mba/webhooks). |
## API response shapes
| Gap | What to do |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `settings`, `skills`, `faq`, `websites`, `files`, and `allowlist` return **bare arrays**, not `{ "data": [ ... ] }`. `settings` is a single-element array. | Parse accordingly. |
| `business_info` is a **closed six-field object** — no custom keys. | Use FAQs/files for anything that doesn't fit the six fields. |
## Connectors
| Gap | What to do |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP connectors are not available** yet (on Meta's roadmap). | Integrate via the REST connector + tool model for now. See [Configure your agent](/docs/mba/meta-business-agent/3.-configure-your-agent). |
## Billing
| Gap | What to do |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ~~Since 1 August, Meta required a client credit line for **all** MBA usage, including allowlisted testing.~~ **Resolved** — `ALLOWLISTED_ONLY` no longer requires a payment method. | Test freely on an allowlist without a payment method; only add one before switching to `EVERYONE`. |
| A payment method is still required before opening the agent to `EVERYONE` — currently a direct credit line; credit-card support is rolling out gradually from **8 September 2026**. | Apply for/add a credit line via Billing Hub, or check whether credit-card support has reached your account. See Roll out to everyone. |
| MBA charges are postpaid, billed at the start of the following month. If credit-line utilization hits 100%, **MBA access is suspended** until resolved. | Monitor utilization and top up / resolve promptly. Consider a usage budget to cap exposure.Monitor utilization and top up / resolve promptly. Consider a usage budget to cap exposure. |
| MBA usage does **not** appear in the standard WhatsApp message billing analytics. | Track usage via Conversation Turns and Budget in the meantime. Meta has also announced near-real-time cost-monitoring APIs, targeted \~15 September 2026. |
***
*Last reviewed: 3rd Sept 2026. Behaviors above may change as Meta ships fixes.*
# Onboarding options
There are three ways to onboard and manage Meta Business Agent on 360dialog. Pick the one that fits how much you want to build yourself.
## Option 1 — Via API
Drive the entire lifecycle yourself through the API: check eligibility, onboard the number, configure knowledge and skills, test, and control the rollout. This is the right choice when you want a **fully custom experience** — for example, when you're building MBA management into your own dashboard or offering it to your own clients.
This is the path the rest of this guide documents, step by step.
**You handle:**
* Onboarding the number (after the Meta Business AI Terms are accepted — see [Enable and accept terms](/docs/mba/meta-business-agent/2.-enable-your-agent)).
* All configuration: skills, FAQs, business info, files, websites, handoff, follow-up, and connectors.
* Rollout control: allowlist, audience, and turning the agent on and off.
## Option 2 — MBA Integrated Onboarding
A hosted, guided onboarding flow — the same idea as 360dialog's **Number Integrated Onboarding**, but for Meta Business Agent. Instead of building the onboarding steps yourself, you send your user (or your client) a link, and the flow handles setup end to end: terms acceptance, onboarding, and configuration — no plumbing to build.
### The link
```
https://app.360dialog.com/client/{clientId}/channel/{channelId}/agent-onboarding
```
`clientId` and `channelId` are the same you already use elsewhere — pull them from Partner Hub or the API.
{% hint style="info" %}
**Coming soon: a generic entry point.** `https://app.360dialog.com/agent-onboarding` (no IDs) will let a user land on a channel picker for their current client and jump into the flow for whichever number they choose. Not live yet — use the direct link with explicit IDs for now.
{% endhint %}
How it behaves
The page opens the guided setup **standalone** — no surrounding Hub navigation — and adapts automatically to the number's current state:
| Number state | What the flow shows |
| ----------------------------------- | ------------------------ |
| No agent yet | Terms step |
| Onboarded but not yet configured | Resumes at Configure |
| Already activated | Manage view |
| Number not eligible for MBA | "Not available" page |
| IDs don't resolve to a real channel | "Channel not found" page |
It's **reload-safe** — every save goes straight to Meta, so refreshing or coming back later picks up exactly where you left off.
The direct link also shows a small channel details card (flag + phone number) at the top, so whoever opens it can confirm which number they're setting up. That card is hidden when the same flow is embedded inside the 360dialog Hub (see Option 3 below) — inside the Hub, the surrounding navigation already makes that clear.
## Option 3 — 360dialog Hub (CHUB)
Enable and manage MBA directly from the 360dialog Hub — no link to send, no integration to build. This is the same Integrated Onboarding flow from Option 2, embedded directly into a channel's page in the Hub.
Open a channel in the Hub and go to its **Agent** tab. The tab header shows the number, its WABA ID, and a **Live** toggle for the agent's status.
Two sub-tabs:
* **Settings** — a **Configure** panel listing every knowledge and behavior building block (Business info, FAQs, Files, Websites, Skills, Connectors, Handoff & follow-up), each showing its current state (e.g. "Configured," "10 FAQs," "4 Skills") and opening into a form to edit it — the same knobs as [Configure your agent](/docs/mba/meta-business-agent/3.-configure-your-agent), without writing any API calls. Alongside it, a **Test your agent** panel lets you chat with a simulated version of the agent and reset the conversation — the UI equivalent of [Test your agent](/docs/mba/meta-business-agent/4.-test-your-agent).
* **Live agent** — monitor and manage ongoing conversations the agent is handling.
# 1. Check Eligibility
Before you can set up Meta Business Agent on a phone number, that number must be eligible. Eligibility is tied to the WhatsApp Business Account (WABA) the number belongs to.
## Eligibility requirements
A phone number is eligible when its WABA meets **all** of the following:
* **Supported vertical.** MBA is available in every business vertical **except** Finance, Government, Health, Alcohol, Gambling, over-the-counter drugs, and matrimony services. A valid business category must be set on the account's profile.
* **Managed through the WhatsApp Business Platform (Cloud API).** The account is on the Cloud API — which is the case with 360dialog — not the WhatsApp Business app.
* **In good standing.** Neither the WABA nor its owning business is restricted or banned on WhatsApp.
* **Meets Meta's business trust and verification requirements.**
* **Not already running a conflicting messaging product** on that number. A single number can't run more than one.
{% hint style="info" %}
**Verticals are defined by exclusion now.** Earlier documentation listed a fixed set of allowed verticals and a country list. Meta has since switched to the exclusion model above — if you're not in one of the excluded verticals, you're in a supported one.
{% endhint %}
## Check a number programmatically
Use the eligibility endpoint to check a specific number.
```bash
curl -s https://waba-v2.360dialog.io/agent_eligibility \
-H "D360-API-KEY: "
```
[Get agent eligibility](/docs/mba/api-ref/onboarding/get-agent-eligibility#get-agent_eligibility)
{% hint style="warning" %}
**A `500 Internal Server Error` on the eligibility check usually means "not eligible," not "server down."** During early access, a non-eligible or not-yet-enabled number returned an HTTP 500 instead of a clean "not eligible" response. Meta has largely resolved this, but if you see a 500 here, first confirm the number really meets the requirements above (vertical, good standing, verification) before treating it as an outage.
{% endhint %}
{% hint style="info" %}
**Regional availability.** MBA rolled out region by region (Brazil first, then the EU in mid-July 2026). The regional restriction appears to have been lifted, so numbers in previously restricted regions should now check out — but if a number in a new region returns not-eligible, region may still be the reason. Re-check after a short wait.
{% endhint %}
Once a number is eligible, continue to [Enable and accept terms](/docs/mba/meta-business-agent/2.-enable-your-agent).
# 2. Enable your agent
Enabling MBA on a number is two things: a one-time terms acceptance in Meta Business Manager, and an onboarding call that prepares the agent. The MBA stays locked until the terms are accepted.
{% hint style="info" %}
**You don't need a payment method yet.** You can enable, configure, test, and go live on an allowlist (steps 2–5) without one. A payment method is only required before you open the agent to `EVERYONE` — see [Roll out to everyone.](/docs/mba/meta-business-agent/6.-roll-out-to-everyone)
{% endhint %}
## Accept the Meta Business AI Terms of Service
The **Meta Business AI Terms** are accepted per WABA, in **Meta Business Manager → WhatsApp Manager → Business AI tab**.
{% hint style="info" %}
Business AI tab may be hidden, but you can always access it using the following urll:
[`https://business.facebook.com/latest/whatsapp_manager/business_ai?business_id={BUSINESS_PORTFOLIO_ID}&asset_id={WABA_ID}`](https://business.facebook.com/latest/whatsapp_manager/business_ai?business_id={BUSINESS_PORTFOLIO_ID}\&asset_id={WABA_ID}) where `business_id` is the Business Portfolio ID and `asset_id` is the WABA ID
{% endhint %}
{% hint style="warning" %}
**Only someone with access to the WABA's *****owning***** Business Manager can accept the terms.** You can open the Business AI page by passing your own Business Manager ID, but the **Accept** action only works if you have access to the business that owns the WABA. If a client owns the WABA, the client (or an admin on the owning BM) must accept. Plan for this in partner setups — it's a common blocker.
{% endhint %}
{% hint style="danger" %}
**API calls return `403 Forbidden` until the terms are accepted.** The error reads: *"The Meta Business AI Terms of Service must be accepted for this WhatsApp Business Account before using this API."* If you see this 403, the terms haven't been accepted for that WABA yet.
{% endhint %}
## Add a valid payment method
Since 1 August, Meta requires a client credit line for Meta Business Agent usage. Meta plans to support credit-card payments in September.
Use Billing Hub to manage the credit line for your Meta Business Agent account:
* If you already have a credit line, add the account in [Billing Hub](https://business.facebook.com/latest/billing_hub/credit_lines/).
* If you need a credit line, apply in [Billing Hub](https://business.facebook.com/latest/billing_hub/credit_lines/).
{% hint style="warning" %}
Credit-line management may not yet be available in the Meta UI. Contact Meta support if Billing Hub does not offer the required action.
{% endhint %}
## Onboard the number
Once the terms are accepted, onboard the number to create the agent's configuration and knowledge scaffolding. This is a required step before you can turn the agent on. You can do it two ways.
**Option A — in WhatsApp Manager (no code).** Right after you accept the terms, an **Onboard** call-to-action appears in the Business AI tab. Click it to onboard the number.
{% hint style="warning" %}
**The "Onboard" button sometimes shows an error even when it worked.** If the CTA returns an error, the number is often onboarded anyway. Wait about a minute and refresh the page before retrying — you'll usually see it's already onboarded.
{% endhint %}
**Option B — via API:**
```bash
curl -s -X POST "https://waba-v2.360dialog.io/agent_onboarding?channel=whatsapp" \
-H "D360-API-KEY: "
```
[Create an onboarding session](/docs/mba/api-ref/onboarding/create-an-onboarding-session#post-agent_onboarding)
Onboarding schedules some background preparation, so it may take a moment before configuration endpoints are fully ready.
{% hint style="info" %}
**Onboarding ≠ live.** After onboarding, the agent still won't reply to customers. It only starts responding once you enable it and set its audience — see [Go live](/docs/mba/meta-business-agent/5.-go-live) and [Roll out to everyone](/docs/mba/meta-business-agent/6.-roll-out-to-everyone). Configure it first ([Step 3)](/docs/mba/meta-business-agent/3.-configure-your-agent).
{% endhint %}
# 3. Configure your Agent
Configuration is where your agent becomes *yours*. You set three things: what it **knows**, how it **behaves**, and what it can **do**. You only need the parts your use case calls for — start small and add more as you iterate.
{% hint style="info" %}
All configuration endpoints live under `agent_config` (and `agent_connectors` for actions), called through 360dialog with your `D360-API-KEY`. For exact routes and every field, see the **Meta Business Agent API reference**. One quirk to know up front: the list endpoints return **bare JSON arrays**, not a `{ "data": [ ... ] }` wrapper — and `settings` comes back as a single-element array.
Endpoints can also fail intermittently with a 4XX or 500 for no clear reason while Meta debugs an ongoing instability — retry after a few hours before assuming your payload is wrong. See Known limitations.
{% endhint %}
***
## Knowledge
### Business info
Core facts about your business, stored as a **fixed set of six fields**. This is where the agent gets hours, policies, and contact details.
{% hint style="warning" %}
**Business info is a closed object — you can't add custom keys.** If a fact doesn't fit one of the six fields, put it in an [FAQ](#faqs) or a [file](#files) instead.
{% endhint %}
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_config/business_info \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"business_description": "Independent bicycle shop selling city, road, and mountain bikes, parts, and repairs.",
"return_policy": "Unused items can be returned within 7 days for a full refund.",
"delivery_and_shipping": "Free local delivery on orders over R$300; nationwide via Correios, 3–10 business days.",
"payment_method": "Pix, credit and debit cards, and cash in store.",
"purchase_info": "Buy in store or on WhatsApp. Reserve a bike with a 20% deposit."
}'
```
[Create or replace business information](/docs/mba/api-ref/knowledge-business-info/create-or-replace-business-information#put-agent_config-business_info)
### FAQs
Question-and-answer pairs the agent draws on. Each FAQ needs a `question` and an `answer`.
{% hint style="info" %}
**Keep FAQs focused, and don't overload.** One specific topic per entry, phrased the way a customer would actually ask ("What is your return policy?" beats "Returns, exchanges, refunds"). Keep answers self-contained — the agent retrieves each entry independently, so don't reference other FAQs. Adding too many (beyond a few hundred) makes it harder for the agent to pick the right one. Prioritize your most common questions.
{% endhint %}
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_config/faq \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"question": "What are your opening hours?",
"answer": "Monday to Friday 9:00–19:00, Saturday 9:00–14:00. Closed Sundays and public holidays."
}'
```
[Create an FAQ](/docs/mba/api-ref/knowledge-faq/create-an-faq#post-agent_config-faq)
### Files
Upload documents (PDFs, images, etc.) as knowledge sources. Uploads are `multipart/form-data`, up to **100 MB** per file.
{% hint style="warning" %}
**File handling has real gaps today — read before relying on it.**
* **File name is mandatory,** and should **include** the **file extension.**
* **CSV files, and tables inside PDFs, error out** when the agent tries to read them. Avoid tabular data in files for now; put critical structured facts into FAQs or business info instead.
* To share files with users, you should use [UI Skills](#ui-skills-optional)
{% endhint %}
```bash
curl --location 'https://waba-v2.360dialog.io/agent_config/files' \
--header 'D360-API-KEY: ' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'file=@"/.../sample.pdf"' \
--form 'file_name="filename_001.pdf"'
```
[Upload a knowledge file](/docs/mba/api-ref/knowledge-files/upload-a-knowledge-file)
**Supported types:** `.pdf`, `.doc`, `.docx`, `.png`, `.jpg`, `.jpeg` , `.csv` and `.xlsx` **Maximum size:** 100,000,000 bytes (100 MB).
### Websites
Give the agent website URLs to crawl and reference. Add a `url` and the agent crawls it; the entry reports a `crawl_status` (e.g. `pending`, `in_progress`, `completed`, `failed`) and how many pages were crawled.
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_config/websites \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{ "url": "https://www.example.com" }'
```
[Add a knowledge website](/docs/mba/api-ref/knowledge-websites/add-a-knowledge-website)
***
## Behavior
### Skills
Skills are the agent's behavioral instructions — its tone, priorities, and brand voice. They're also how you **teach the agent your processes**: encode an existing business workflow (how you qualify a lead, take a booking, triage a support request) as ordered steps in a skill, and the agent follows it. This lets you reuse the processes you already run rather than inventing new ones.
{% hint style="info" %}
**Write skills as clear directives, and avoid conflicting priorities.** The agent follows skills literally. If two skills both claim to go "first" on the same trigger, the agent can produce duplicate or inconsistent replies. When several actions should happen on one trigger, put them in **a single skill with explicitly ordered steps** rather than splitting them across skills.
{% endhint %}
Each skill has three parts:
* `title` — a short name, **lowercase letters, numbers, and hyphens only** (e.g. `product-return-policy`), max 64 characters.
* `description` — *when* to apply the skill (e.g. "Apply when the customer asks about returns or refunds"), max 1024 characters. The agent uses this to decide relevance.
* `skill` — the actual instructions, max 20,000 characters.
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_config/skills \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"title": "polite-grounded-support",
"description": "Apply to every customer message as the main support persona.",
"skill": "You are the support assistant for our shop. Be warm, polite, and concise. Answer ONLY from the business info, FAQs, files, and tools provided. If the answer is not covered, do not guess — apologize briefly and hand off to a human. Never invent prices, stock, or policies."
}'
```
[Create a skill](/docs/mba/api-ref/knowledge-skills/create-a-skill)
### Handoff
Handoff hands the conversation from the agent to a human. It's part of the agent **settings** object — set `handoff.enabled` and an optional `message`.
```bash
curl -s -X PUT https://waba-v2.360dialog.io/agent_config/settings \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"handoff": { "enabled": true, "message": "Connecting you to a human agent." }
}'
```
{% hint style="warning" %}
**Handoff behavior to design around:**
* **Once the agent hands a chat to a human, it stops answering that chat.** A working human-handover path is essential — otherwise those customers get no replies.
* **The handoff notice is the fixed `message` you define** — it can't be adapted per customer language. For a multilingual audience, keep the message simple or language-neutral.
* **On hand-back, the agent loses the earlier conversation context.** Don't assume it remembers what was said before the human stepped in.
* **There's no endpoint to read who currently holds the thread** — infer it from the `standby` vs `messages` routing and the `messaging_handovers` events on your webhook. See [Webhooks](/docs/mba/webhooks)
{% endhint %}
[Update AI agent settings](/docs/mba/api-ref/onboarding/update-ai-agent-settings)
### Follow-up
Follow-up sends a nudge after a period of customer inactivity. Also part of **settings** — set `followup.enabled`, a `message`, and `followup_interval_in_seconds`.
The interval must be one of: `0` (disabled), `300`, `900`, `1800`, `3600`, `7200`, `28800`, or `86400` seconds.
{% hint style="info" %}
`settings` is a singleton (one per number) and is replaced with `PUT`. It also holds `rollout` (on/off) and `ai_audience` — the two levers you'll use in [Go live](/docs/mba/meta-business-agent/5.-go-live) and [Roll out to everyone](/docs/mba/meta-business-agent/6.-roll-out-to-everyone).
{% endhint %}
```bash
curl -s -X PUT https://waba-v2.360dialog.io/agent_config/settings \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"followup": { "enabled": true, "followup_interval_in_seconds": 3600, "message": "Is there anything else I can help with?" }
}'
```
[Update AI agent settings](/docs/mba/api-ref/onboarding/update-ai-agent-settings)
### UI Skills (optional)
{% hint style="info" %}
**This step is optional.** UI Skills aren't required to launch an agent — they're a polish layer on top of regular Skills, for when a plain text reply isn't the best way to answer. Add them once your core Skills, knowledge, and (if needed) connectors are working.
{% endhint %}
Regular Skills tell the agent *how to think and respond*. **UI Skills** tell it *when to reply with a rich WhatsApp component* instead of plain text — a button, an image, a list, a carousel, a location share, or a Flow. Like Skills, each UI Skill is a natural-language `instruction`: you don't build the JSON payload yourself, you describe in plain language when the agent should use the component and what to put in it. The agent fills in the actual message at send time.
Each UI Skill has:
* `title` — a human-readable name for the UI skill.
* `component_type` — which rich message format to send (see table below).
* `status` — `enabled` or `disabled`.
* `instruction` — natural-language description of *when* to send this and *what* to put in each field. This is the main thing you write.
* `flow_id` — only required (and only allowed) when `component_type` is `flow`.
{% hint style="info" %}
**Write the `instruction` like you're briefing the agent, not filling a form.** State the trigger condition clearly (e.g. "when a customer asks for a link to our catalog") and describe every field the component needs (button label, URL, caption, options, etc.) in the same sentence or two. Vague instructions are the most common reason a component fires at the wrong time, or with the wrong content.
{% endhint %}
**Supported component types:**
| `component_type` | Sends | Notes |
| --------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
| `cta_url` | Text + a clickable button linking to a URL | Optional image/video header and footer text |
| `image` | A standalone image | By URL or a previously uploaded media ID, with optional caption |
| `interactive_list` | A dropdown of 1–10 selectable options | Each option needs an ID, title, and optional description |
| `interactive_reply_buttons` | Up to 3 quick-reply buttons | Selections are returned to the agent to continue the conversation |
| `location` | A pinned location | Latitude/longitude plus optional business name and address |
| `location_request` | A button asking the customer to share their location | |
| `carousel_url` | 2–10 scrollable cards, each with a URL button | Cards navigate the customer away from the chat |
| `carousel_quick_reply` | 2–10 scrollable cards, each with a quick-reply button | Keeps the customer in the conversation, unlike `carousel_url` |
| `flow` | Launches an existing WhatsApp Flow | Requires `flow_id` of a **published** flow |
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent-ui-skills \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"title": "product-catalog-button",
"component_type": "cta_url",
"status": "enabled",
"instruction": "When a customer asks to see the full product catalog or asks for a link to browse online, send a CTA button. Body text: a short, friendly line inviting them to browse. Button label: \"View catalog\". Button URL: https://www.example.com/catalog."
}'
```
[Create a UI skill](/docs/mba/api-ref/ui-skills/create-a-ui-skill)
{% hint style="warning" %}
* **`component_type` and `flow_id` can't be changed after creation.** To change the message type, delete the UI skill and create a new one.
* **A `flow` UI skill can't be enabled until its Flow is published.** Publish the Flow first, then create or enable the UI skill.
* Only `title`, `status`, and `instruction` can be changed with an update — see [Update a UI skill.](/docs/mba/api-ref/ui-skills/update-a-ui-skill)
{% endhint %}
***
## Connectors and tools
Connectors let the agent do more than answer questions — they call your own APIs to look up an order, book an appointment, or check inventory. It's a two-level setup:
{% hint style="info" %}
**Write descriptions like you're briefing the agent.** Give each connector and tool a clear `name` and `description`, and define the request body with explicit field types, descriptions, and required fields. Vague descriptions are the top cause of the agent calling a tool at the wrong time — or not at all. See the **Meta Business Agent API reference** for the full `request_definition` and user-auth injection schema.
{% endhint %}
{% stepper %}
{% step %}
## Connector
Defines an external API: `name`, `description`, `base_url`, and `auth_type`. Supported auth types today are `OAUTH2_CLIENT_CREDENTIALS`, `API_KEY`, and `NONE`.
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_connectors \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"name": "Order Management",
"description": "Looks up customer orders and returns status and tracking.",
"base_url": "https://api.yourshop.example/v1",
"auth_type": "API_KEY"
}'
```
[Create a connector](/docs/mba/api-ref/knowledge-connectors/create-a-connector)
{% endstep %}
{% step %}
## Connector tool
A single operation on that connector: `name`, `description`, and a `request_definition`. The agent reads these to decide when to call the tool and how to build the request.
```bash
# 2) Add a tool to it (use the connector id from the response above)
curl -s -X POST https://waba-v2.360dialog.io/agent_connectors//tools \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"name": "check_order_status",
"description": "Use when a customer asks about an existing order. Requires an order ID. Returns status, estimated delivery, and tracking.",
"user_auth_required": false,
"request_definition": { "method": "GET", "path": "/orders/{order_id}" }
}'
```
[Create a connector tool](/docs/mba/api-ref/knowledge-connector-tools/create-a-connector-tool)
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**MCP connectors are not available yet.** Support for MCP-based connectors is on Meta's roadmap (requested by many partners) but not shipped. For now, integrate via the REST connector model above.
{% endhint %}
# 4. Test your Agent
Before customers reach your agent, send it test messages and check the replies. The test endpoint returns the agent's response plus useful diagnostics — no real WhatsApp message is sent.
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_test \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{ "user_msg": "Do you deliver to Rio?" }'
```
[Run an agent test](/docs/mba/api-ref/operate/run-an-agent-test)
{% hint style="info" %}
**A 4XX or 500 from `agent_test` isn't always a real error.** Endpoints occasionally fail with no obvious cause while Meta debugs an ongoing instability. Retry after a few hours before treating it as a configuration problem. See [Known limitations](/docs/mba/meta-business-agent/known-limitations#platform-stability).
{% endhint %}
The response includes `agent_response` (the reply text), `conversation_id`, `handoff_reason`, `no_response_reason`, `quick_replies`, and `product_variant_ids`.
## How to test safely today
Because of the caveat above, the practical way to test before a public launch is to **test on real WhatsApp under an allowlist**, not through `agent_test`:
1. Set `ai_audience` to `ALLOWLISTED_ONLY` and add your own phone numbers to the [allowlist](/docs/mba/meta-business-agent/5.-go-live).
2. Message the agent from those allowlisted numbers on WhatsApp and observe the replies directly on the phone.
3. Iterate on skills, FAQs, and business info, then repeat.
Use `agent_test` for quick automated checks in environments where it's acceptable to have the agent on `EVERYONE` (for example, a dedicated test number), and use the allowlist-on-real-WhatsApp method for pre-launch validation of a production number.
{% hint style="info" %}
**Each `agent_test` call starts a fresh conversation** unless you pass a `conversation_id` back in to continue a thread. The consumer/`to` field is ignored. So to test a multi-turn flow, capture the `conversation_id` from the first response and send it with the next message.
{% endhint %}
{% hint style="success" %}
**You can watch a live agent conversation over webhooks.** While the agent holds a conversation, the consumer's messages and the agent's replies arrive on the `standby` field of your number's webhook, alongside `messaging_handovers` and `bizai`-tagged delivery statuses. This makes allowlist testing on real WhatsApp observable end to end — see [Webhooks](/docs/mba/webhooks)
{% endhint %}
Once you're happy with the replies, continue to [Go live with an allowlist](/docs/mba/meta-business-agent/5.-go-live).
{% hint style="info" %}
**Want to see exactly why the agent replied the way it did?** Once you've sent a test message, look up that conversation's turns — including which tools were called and how long each step took — in [Controlling your Agent.](/docs/mba/meta-business-agent/controlling-your-agent)
{% endhint %}
# 5. Go live
Don't flip the agent on for every customer at once. Release it to a small, controlled set of numbers first, watch how it behaves on real conversations, and fix what you learn. That's what the **allowlist** is for.
## How the allowlist works
The agent's audience is controlled by the `ai_audience` setting:
* **`ALLOWLISTED_ONLY`** — the agent responds only to consumers whose numbers are on the allowlist. Everyone else is handled as if the agent weren't there.
* **`EVERYONE`** — the agent responds to all consumers (that's [full rollout](/docs/mba/meta-business-agent/6.-roll-out-to-everyone)).
## Turn on a controlled launch
{% stepper %}
{% step %}
## Add your test numbers to the allowlist
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_config/allowlist \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+49123456789" }'
```
[Add to allowlist](/docs/mba/api-ref/onboarding/add-to-allowlist)
{% endstep %}
{% step %}
## Enable the agent and set the audience to allowlist-only
```bash
curl -s -X PUT https://waba-v2.360dialog.io/agent_config/settings \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"rollout": { "enabled": true },
"ai_audience": "ALLOWLISTED_ONLY"
}'
```
[Update AI agent settings](/docs/mba/api-ref/onboarding/update-ai-agent-settings)
Now only the numbers you added will talk to the agent.
{% endstep %}
{% endstepper %}
## Iterate
Treat the controlled launch as a feedback loop:
1. **Message the agent** from allowlisted numbers on real WhatsApp.
2. **Watch the replies** — on the phone, or by logging the `standby` webhook events. Is it grounded, on-brand, and handing off when it should?
3. **Refine** skills, FAQs, and business info based on what you see.
4. **Expand the allowlist** gradually — add colleagues, then friendly customers.
5. Repeat until you're confident.
{% hint style="warning" %}
**Reminder: `agent_test` won't return replies under `ALLOWLISTED_ONLY`.** During the allowlist phase, validate by messaging from allowlisted numbers on WhatsApp rather than the test endpoint. See [Test your agent](/docs/mba/meta-business-agent/4.-test-your-agent) for why.
{% endhint %}
{% hint style="success" %}
**You can monitor the allowlist phase over webhooks.** While the agent holds a chat, consumer messages and agent replies arrive on the `standby` field of your number's webhook — so you can log and review real conversations instead of reading them off the phone. See [Webhooks](/docs/mba/webhooks).
{% endhint %}
{% hint style="info" %}
**Have your human-handoff path ready before you go live**, even in the allowlist phase. Once the agent hands a chat to a human it stops replying — so make sure a human can actually pick up. See [handoff](/docs/mba/meta-business-agent/3.-configure-your-agent).
{% endhint %}
When the agent performs well for your allowlist, you're ready to [roll out to everyone](/docs/mba/meta-business-agent/6.-roll-out-to-everyone).
# 6. Roll out to everyone
{% hint style="warning" %}
**A payment method is required before this step.** Opening the agent to `EVERYONE` needs a valid payment method on file with Meta:
* **Today:** a direct credit line. Use Billing Hub to manage it — apply for one if you don't have it yet, or add your existing account.
* **From 8 September 2026:** credit-card support as an alternative, rolling out gradually (some accounts may see it before others).
Testing under `ALLOWLISTED_ONLY` (steps 1–5) does **not** require a payment method.
{% endhint %}
{% hint style="info" %}
**Billing mechanics:** MBA charges are **postpaid** — billed at the start of the following month, no prepayment and no mid-month charges. If you're on a credit line, hitting **100% utilization suspends MBA access** until it's resolved. MBA usage does **not** yet appear in the standard WhatsApp message billing analytics — see Controlling your Agent for how to track and cap spend in the meantime.
{% endhint %}
When the agent has proven itself with your allowlist, open it to all customers by switching the audience to `EVERYONE`.
```bash
curl -s -X PUT https://waba-v2.360dialog.io/agent_config/settings \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"rollout": { "enabled": true },
"ai_audience": "EVERYONE"
}'
```
[Update AI agent settings](/docs/mba/api-ref/onboarding/update-ai-agent-settings)
From now on, the agent is the primary responder for every new conversation on that number.
### After you roll out
* **Keep iterating.** Real traffic surfaces new questions. Keep adding FAQs and refining skills as you see what customers actually ask.
* **Watch the handoff path.** At full volume, make sure humans can keep up with handoffs — the agent goes silent on a chat the moment it hands off.
* **Turn it off any time.** Set `rollout.enabled` to `false` to stop the agent responding to new conversations, or drop back to `ALLOWLISTED_ONLY` to narrow the audience again. Configuration is preserved.
```bash
# Pause the agent
curl -s -X PUT https://waba-v2.360dialog.io/agent_config/settings \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{ "rollout": { "enabled": false } }'
```
[Get AI agent settings](/docs/mba/api-ref/onboarding/get-ai-agent-settings)
***
That's the full journey. Once you're live, see [Controlling your Agent](/docs/mba/meta-business-agent/controlling-your-agent) for ongoing operation — usage budgets, taking over a conversation, and diagnosing individual replies — and [Known limitations & workarounds](/docs/mba/meta-business-agent/known-limitations) for every gap referenced along the way.
# Controlling your Agent
Once your agent is live, these are the controls you'll come back to again and again: capping what it can spend, stepping into a conversation yourself, and seeing exactly what it did on a given reply.
## Billing
MBA charges are **postpaid**: usage is billed at the start of the following month — no prepayment, no mid-month charges. A payment method (credit line today, credit card from 8 September 2026) is required before the agent can answer everyone — see [Roll out to everyone.](/docs/mba/meta-business-agent/6.-roll-out-to-everyone)
{% hint style="warning" %}
**If your credit line hits 100% utilization, MBA access is suspended** until it's resolved. Set a usage budget below to cap spend before you get there.
{% endhint %}
MBA usage doesn't yet appear in the standard WhatsApp message billing analytics.
{% hint style="info" %}
**Coming \~15 September 2026 (target):** Meta is planning new APIs to monitor token consumption and cost in near real time. We'll document them here once they ship.
{% endhint %}
***
## Usage budget
Set a spending cap so the agent can't run away with usage. A budget limits how much of something — tokens, or AI-handled turns — the agent can consume within a rolling time window. When the cap is reached, the agent stops responding until the window resets.
You can set more than one budget at once (e.g. a tight daily cap and a looser 30-day cap). **Whichever one is reached first takes effect.**
Each budget has:
* `budget_id` — omit when creating a new budget (the server assigns one); pass it back to edit or keep an existing budget.
* `unit_type` — what's being measured: `token` or `ai_turn`.
* `time_window` — the rolling period usage is totalled over, in the WhatsApp Business Account's timezone: `one_day`, `seven_days`, `fourteen_days`, or `thirty_days`.
* `max_budget` — the cap itself, a positive whole number.
{% hint style="warning" %}
**This call replaces the entire set of budgets, not just the one you're changing.** Send every budget you want to keep on each request — anything left out is removed. An empty `budgets` array clears all limits and returns the agent to unlimited usage. A given `unit_type` + `time_window` pair can only appear once.
{% endhint %}
```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_budget \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"budgets": [
{ "unit_type": "token", "time_window": "one_day", "max_budget": 500000 },
{ "unit_type": "token", "time_window": "thirty_days", "max_budget": 10000000 }
]
}'
```
[Replace the agent budgets](/docs/mba/api-ref/budget/replace-the-agent-budgets)
{% hint style="info" %}
**Billing itself is still being defined by Meta**, separately from these budgets — see Known limitations. A usage budget is a hard technical cap you control; it isn't the same as (and doesn't depend on) Meta finalizing pricing.
{% endhint %}
***
## Thread control
The agent is the primary responder and holds each conversation by default. Your team or systems will sometimes need to step into a conversation it's handling — and hand it back afterward.
While the agent is in control, the consumer's messages and the agent's replies reach you on the `standby` field. **The moment you send a message to that conversation, you take control**: from then on the consumer's messages arrive on `messages` and the agent stays quiet. When you're done, hand control **back to the agent** using the Thread Control endpoint's `release` action:
```bash
curl -s -X POST "https://waba-v2.360dialog.io/business/whatsapp/phone_numbers//thread_control" \
-H "D360-API-KEY: " \
-H "X-API-Version: 1.0.0" \
-H "Content-Type: application/json" \
-d '{ "messaging_product": "whatsapp", "action": "release", "to": "" }'
```
[Transfer thread control](/docs/mba/api-ref/operate/transfer-thread-control)
Every control change also emits a `messaging_handovers` webhook, so you can keep track of who currently holds a conversation — when `previous_owner_app_role` is `meta_business_agent`, the agent has just passed control to you. There's no endpoint to query the current owner, so rely on these events (together with the `standby` vs `messages` routing) to track control state. See Webhooks for the payloads. Note that `release` is the only supported action — you take control implicitly by sending a message, not through an explicit "take" call.
***
## Conversation turns
When a reply looks wrong, slow, or never arrives, don't just re-read the final message — look at the **turns**. For a given customer, this returns their most recent conversation broken down into ordered turns, and for each turn, the internal steps the agent took to produce it: every `LLM_CALL` and `TOOL_CALL`, with per-step latency and status. This is the fastest way to see *why* a reply came out the way it did — which tool got called (and with what input/output), which step was slow, or which step errored or timed out.
```bash
curl -s -G https://waba-v2.360dialog.io/insights/conversations/turns \
-H "D360-API-KEY: " \
-H "Content-Type: application/json" \
--data-urlencode "user_phone_number="
```
`user_phone_number` is required — digits only, country code included, no `+` or separators (e.g. `15551234567`). You can optionally narrow the window with `start_timestamp_ms` / `end_timestamp_ms`, and page through results with `before` / `after` / `limit`.
Each turn includes:
* `turn_id` — a stable identifier for the turn.
* `conversation_id` — the conversation this turn belongs to.
* `message_id` — the corresponding WhatsApp Cloud API message ID.
* `timestamp` — when the turn happened.
* `e2e_latency_ms` — total end-to-end processing time for the turn.
* `steps` — the ordered list of internal steps that produced the reply. Each step has a `type` (`LLM_CALL` or `TOOL_CALL`), a `status` (`SUCCESS`, `ERROR`, or `TIMEOUT`), and a `latency_ms`. An `LLM_CALL` step includes an `llm_output_preview`; a `TOOL_CALL` step includes the `tool_name`, `tool_input`, and `tool_output`.
{% hint style="info" %}
**Pair this with allowlist testing.** Message the agent from an allowlisted number (see [4. Test your Agen](/docs/mba/meta-business-agent/4.-test-your-agent)t), then pull that number's turns to see the full step-by-step trace behind the reply you just got — much faster than guessing from the final text alone. It's just as useful once you're live: pull turns for any real customer number to debug a reported issue.
{% endhint %}
# FAQ
Answers to the questions we hear most while clients integrate Meta Business Agent (MBA). For anything not covered here, check [Known limitations & workarounds](/docs/mba/meta-business-agent/known-limitations) or reach out to your 360dialog contact.
## Getting started
Do I need a credit line to try MBA?
**No — not to test it.** You can complete eligibility, enable, configure, test, and go live on an **allowlist** (`ALLOWLISTED_ONLY`) without any payment method on file. A payment method is only required before you switch the agent to answer **everyone** (`EVERYONE`). See [Roll out to everyone](broken://pages/10764817115f371018b21b4c45e35fa609ba193e).
What payment methods are supported?
Today, a **direct credit line** with Meta, managed via Billing Hub. **From 8 September 2026**, credit-card payment is also supported as an alternative, rolling out gradually — some accounts may see it before others.
Can I use 360dialog's (or my partner's) credit line for a client's MBA?
**No.** A credit line belongs to the **Business Manager that owns the WABA**, and MBA billing follows that same rule — a 360dialog or tech-provider credit line can't be reused for an end client's agent, even if that credit line is already attached to the WABA for other purposes. Each client needs to add or apply for **their own** credit line.
My client's Business Portfolio doesn't even show an option to apply for a credit line — what can they do?
There's no workaround today. Two options: wait for credit-card support, or have the client check their eligibility directly on Meta's **Payment Methods** page in Business Manager — 360dialog can't apply for a credit line on a client's behalf.
How is MBA billed?
Usage is **postpaid**: charged at the start of the following month. There's no prepayment and no mid-month charge. If you're on a credit line and utilization hits **100%**, MBA access is **suspended** until it's resolved — a [usage budget](/docs/mba/api-ref/budget) is the practical way to avoid hitting that ceiling unexpectedly.
Does MBA usage show up in my normal WhatsApp billing analytics?
**Not yet.** MBA usage doesn't currently appear in the standard WhatsApp message billing analytics. In the meantime, track usage via [Conversation Turns](/docs/mba/meta-business-agent/controlling-your-agent#conversation-turns) and [Budget](/docs/mba/api-ref/budget). Meta has also announced near-real-time cost-monitoring APIs, targeted for around 15 September 2026 — we'll document them once they ship.
Does the pricing change coming 1 October 2026 affect MBA?
**No — MBA pricing itself doesn't change.** The 1 October update is about **service messages sent by anything other than MBA** (a human agent, or your own 3rd-party AI/backend) — those start being billed per message from that date, with one exception: the **first 1,000 service messages per phone number per month are free**. That free allowance applies to non-MBA service messages, not to MBA messages, and it counts per message, not per conversation.
MBA messages have been billed separately since 1 August 2026, at a flat rate of **$2.00 per 1 million tokens (roughly 4–5 US cents per message)**, covering message delivery and AI processing in a single charge. Nothing about that rate or mechanism changes on 1 October.
How do I onboard — API, or something more hands-off?
Three ways, depending on how much control you want:
* **Via API** — build your own onboarding and management experience. Full control, available today. This guide covers that path.
* **MBA Integrated Onboarding** — a hosted, guided flow (similar to 360dialog's Number Integrated Onboarding) that handles terms acceptance and setup for you. Live now.
* **360dialog Hub** — enable and manage MBA directly from the Hub UI, no integration work at all. Best for a single account that doesn't need programmatic control.
See [three ways to onboard](/docs/mba/meta-business-agent/onboarding-options).
Is MBA available for my number?
It depends on eligibility (account type, region, and a few other factors) — run the eligibility check before assuming. See [1. Check eligibility](broken://pages/4cac515345e60e760b3dbaa26131561ecc759cfa). Availability was regional during early rollout (Brazil first, EU from mid-July 2026); that restriction appears lifted, but if a number in a newer region reads as not-eligible, re-check after a short wait.
Can I use MBA on Instagram?
**Not today.** Meta's current MBA documentation covers Messenger and WhatsApp only; Instagram is mentioned as a future direction but isn't available yet. Set up and configure the agent for WhatsApp as usual — if Instagram support ships, it's expected to be the same underlying agent, just connected to an additional channel, not a separate setup.
## Testing
Can I test MBA before opening it to real customers?
Yes — that's what the **allowlist** is for. Set `ai_audience` to `ALLOWLISTED_ONLY`, add your own numbers, and message the agent from those numbers on real WhatsApp. See [5. Go live](broken://pages/41fca983d6a89018609dbd2994b4e348a73f714b).
Does the agent_test endpoint work during allowlist testing?
Use it for quick automated checks (it starts a fresh conversation each time unless you pass back a `conversation_id`), but for validating a production number before public launch, testing on real WhatsApp under an allowlist is the more representative method. See [4. Test your Agent](broken://pages/af20ef977eb3ff40523d1c5fe492bd6cb68ab279).
How do I see why the agent replied the way it did?
Pull that conversation's **turns** — each one shows the internal steps the agent took (which tool it called, what it returned, how long each step took, and whether anything errored or timed out). See [Conversation turns](broken://pages/674987a5a511629914f8e8eb6db6a740d2a8eb2a#conversation-turns).
## Configuration
What can I actually teach the agent?
Three things: **knowledge** (business info, FAQs, files, websites it can reference), **behavior** (skills — your workflows and tone, written as natural-language directives), and **capabilities** (connectors and tools that call your own APIs, plus UI Skills for rich WhatsApp components). See [3. Configure your agent](broken://pages/03202bdfc6d5f6746c0847acade45c6f4b350019).
Can I upload a spreadsheet or a PDF with a table as a knowledge source?
Not reliably today. **CSV files, and tables inside PDFs, error out** when the agent tries to read them. Put structured or tabular facts into FAQs or business info instead. See [Known limitations](broken://pages/ae9ce6e2eef77e7388a9ae943bf2c8c9a6801faa#files).
Can the agent send a file or image back to a customer?
Yes. Sending **rich messages** (images, buttons, carousels, lists, locations, flows) via [UI Skills](broken://pages/03202bdfc6d5f6746c0847acade45c6f4b350019#ui-skills-optional) is supported and is the right tool for that.
What's the difference between a regular Skill and a UI Skill?
A regular **Skill** tells the agent how to think and respond — tone, priorities, workflows, all in plain text. A **UI Skill** tells it *when* to reply with a rich WhatsApp component instead — a button, image, list, carousel, location, or Flow — again as a natural-language instruction rather than a JSON payload you build yourself. See [UI Skills](broken://pages/03202bdfc6d5f6746c0847acade45c6f4b350019#ui-skills-optional).
Can I connect the agent to my own systems (order lookup, booking, inventory)?
Yes, via **Connectors and tools** — you define an external API once (a Connector), then add individual operations on it (Connector Tools) with a clear description so the agent knows when and how to call them. See [Connectors and tools](broken://pages/03202bdfc6d5f6746c0847acade45c6f4b350019#connectors-and-tools).
Can I connect an MCP server as a connector?
**Not yet.** MCP-based connectors are on Meta's roadmap but not shipped. Integrate via the REST connector + tool model for now. See [Known limitations](broken://pages/ae9ce6e2eef77e7388a9ae943bf2c8c9a6801faa#connectors).
Can I cap how much the agent spends?
Yes — set a **usage budget**, capping token or AI-turn usage within a rolling time window (one day up to thirty days). Once the cap is hit, the agent stops responding until the window resets. See [Usage budget](broken://pages/674987a5a511629914f8e8eb6db6a740d2a8eb2a#usage-budget).
Can I make the agent send a specific, exact-match message at a certain point (e.g. for conversion tracking)?
You can instruct it to — write a skill telling the agent to reply with an exact phrase when a specific condition is met (e.g. "once the booking is confirmed, reply with exactly: '...'"). In our own testing this behaves as expected, but treat it the way you would any AI-generated output: it's a strong instruction, not a hard guarantee of byte-for-byte output every time. If you're wiring this into an exact-match tracking system (e.g. a conversion tool that matches on literal text), monitor it after launch rather than assuming it'll never drift.
## Handoff & control
What happens when the agent hands off to a human?
It **stops answering that chat** entirely — make sure a human handover path is actually staffed before you launch, or those customers get silence. On hand-back, the agent also **loses the earlier conversation context**, so don't assume continuity across a handoff. See [Configure your agent — Handoff](broken://pages/03202bdfc6d5f6746c0847acade45c6f4b350019#handoff).
Can I take over a conversation the agent is handling, and give it back?
Yes. You take control implicitly the moment you send a message to that conversation — from then on, the consumer's messages arrive on `messages` instead of `standby`, and the agent stays quiet. Hand it back with the Thread Control endpoint's `release` action. There's no endpoint to *read* who currently holds a conversation — infer it from `messaging_handovers` webhook events. See [Thread control](broken://pages/674987a5a511629914f8e8eb6db6a740d2a8eb2a#thread-control).
Does the agent always reply in the customer's language?
Not always automatically — reinforce language behavior explicitly in your skills where it matters.
Can I A/B test MBA against my existing WhatsApp flow on the same number?
Yes, but it's not a built-in percentage-split toggle — you build the split into your own routing. The pattern: keep your existing flow as the default, and only **release thread control to MBA** for the subset of conversations you want in the test (for example, a random split at the point a user enters a specific journey). MBA doesn't take over a conversation until thread control is released to it, so whatever owns your routing logic upstream — your flow builder, your backend — decides which users get the MBA-led experience. See [Thread control](broken://pages/674987a5a511629914f8e8eb6db6a740d2a8eb2a#thread-control).
## Known limitations & open questions
Is the platform stable enough for production traffic?
MBA is still in early access. Endpoints can intermittently return a 4XX or 500 with no obvious cause while Meta debugs ongoing instability — this isn't necessarily a sign your configuration is wrong; retry after a few hours before treating it as a real error. See [Known limitations — Platform stability](broken://pages/ae9ce6e2eef77e7388a9ae943bf2c8c9a6801faa#platform-stability).
Is billing fully finalized?
Not entirely. The payment-method mechanics above are confirmed, but Meta is still shipping billing-related tooling (e.g. the near-real-time cost APIs targeted for mid-September) and MBA usage still isn't in standard billing analytics. Treat commercial terms as provisional and check [Known limitations](broken://pages/ae9ce6e2eef77e7388a9ae943bf2c8c9a6801faa#billing) for the latest.
Can I read who currently owns a conversation via the API?
No — there's no `GET` for thread control today; only `release` is supported, and ownership has to be inferred from webhook events (`messaging_handovers`) and the `standby` vs `messages` routing. We've asked Meta for a read endpoint.
Will agent_test ever work properly under ALLOWLISTED_ONLY?
Historically it didn't — it required the agent to be fully published (`EVERYONE`) to return a real reply. Check [4. Test your Agent](broken://pages/af20ef977eb3ff40523d1c5fe492bd6cb68ab279) for the current behavior, since this is one of the areas Meta has been actively changing.
What's still coming that isn't documented yet?
* **Near-real-time token/cost monitoring APIs** — targeted around 15 September 2026.
* **MCP-based connectors** — on Meta's roadmap, no date yet.
* **A thread-control read endpoint** — requested, no date yet.
We'll fold each of these into the relevant page as soon as they ship — this FAQ and [Known limitations](broken://pages/ae9ce6e2eef77e7388a9ae943bf2c8c9a6801faa) are the two pages to check back on.
# Webhooks
Webhooks are how you follow what happens on a number running Meta Business Agent — the customer's messages, the agent's replies, control changes, and delivery receipts. This page explains what you'll receive and how MBA conversations map to webhook fields.
## Webhook setup is handled for you
**You don't need to set anything up to receive MBA events.** They're delivered to the same 360dialog webhook you already use for your number's messages, signed with `x-360dialog-signature`. You'll receive three fields:
* **`messages`** — consumer messages that arrive while **you** hold the conversation.
* **`standby`** — the **agent's** conversation: consumer messages *and* the agent's replies while **the agent** holds the conversation.
* **`messaging_handovers`** — fired whenever control of a conversation changes between the agent and you.
You just need to handle these fields on your existing webhook — see how they map to conversations below.
## How conversations map to fields
When your agent is enabled it is the **primary responder** and holds the conversation by default. Which field a consumer's message arrives on depends on who holds control at that moment:
| Who holds control | Consumer message arrives on | Agent replies arrive on |
| -------------------------------- | --------------------------- | ----------------------------- |
| **The agent** (default) | `standby` | `standby` (as message echoes) |
| **You** (after you take control) | `messages` | n/a — you send them |
You **take control** simply by sending a message to the conversation. To hand control **back** to the agent, use the [Thread Control `release` action](/docs/mba/api-ref/operate/transfer-thread-control). Every control change also produces a [`messaging_handovers` event](#the-messaging_handovers-payload).
## The `standby` payload
The `standby` field uses the standard WhatsApp webhook envelope. Inside `value.standby` you get the full agent conversation:
* **`standby.messages[]`** — the consumer's inbound messages.
* **`standby.message_echoes[]`** — the agent's replies. These are **bizai-tagged**: `message.biz_opaque_callback_data` contains `{"originator":"bizai", ...}`, which is how you tell an agent-generated message apart from your own.
Route on the phone number using `value.metadata.phone_number_id` (or the WABA id at `entry[].id`).
**Consumer inbound** (`standby.messages[]`):
```json
{
"object": "whatsapp_business_account",
"entry": [{ "id": "", "changes": [{
"field": "standby",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "551146733503", "phone_number_id": "" },
"standby": {
"contacts": [{ "profile": { "name": "Grzegorz G" }, "wa_id": "48883042025" }],
"messages": [{
"from": "48883042025",
"id": "wamid...",
"timestamp": "1784107832",
"text": { "body": "Do you repair ebikes?" },
"type": "text"
}]
}
}
}]}]
}
```
**Agent reply** (same `standby` field, `standby.message_echoes[]`):
```json
{
"object": "whatsapp_business_account",
"entry": [{ "id": "", "changes": [{
"field": "standby",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "551146733503", "phone_number_id": "" },
"standby": {
"message_echoes": [{
"id": "wamid...",
"timestamp": "1784296217",
"message": {
"to": "34680989836",
"type": "text",
"biz_opaque_callback_data": {
"originator":"bizai",
"channel":"ent"
},
"text": { "body": "I'm sorry, but we don't offer bike rentals at Pedala Bikes. ..." }
}
}]
}
}
}]}]
}
```
{% hint style="success" %}
## Where `standby` is delivered
**The agent's conversation now arrives on your number's own webhook.** Meta delivers `standby` only to a single account-wide destination, so 360dialog routes each number's `standby` events to that number's webhook and re-signs them with `x-360dialog-signature`. You validate them with your existing webhook secret — nothing to configure on your side.
This means you now receive the full agent conversation over webhooks: consumer inbound (`standby.messages[]`), agent replies (`standby.message_echoes[]`), `messaging_handovers`, and `bizai`-tagged delivery statuses. You can build monitoring and logging on top of it.
{% endhint %}
## The `messaging_handovers` payload
A `messaging_handovers` event fires whenever control of a conversation changes. Use it to know when the agent has handed a conversation to you (or vice versa).
The key fields: `value.type` describes what happened (e.g. `control_passed`), and `value.control_passed.previous_owner_app_role` tells you who held control before the change. When that role is **`meta_business_agent`**, the agent has just passed control to you — your side is now responsible for the conversation. `value.sender.phone_number` is the consumer, and `value.recipient.phone_number_id` identifies your number.
```json
{
"object": "whatsapp_business_account",
"entry": [{ "id": "", "changes": [{
"field": "messaging_handovers",
"value": {
"messaging_product": "whatsapp",
"recipient": { "display_phone_number": "551146733503", "phone_number_id": "" },
"sender": { "phone_number": "34680989836" },
"timestamp": "1784296293",
"type": "control_passed",
"control_passed": {
"previous_owner_app_role": "meta_business_agent",
"metadata": "unknown"
}
}
}]}]
}
```
## Signature validation
MBA webhooks 360dialog forwards to you are signed exactly like your normal message callbacks — with the **`x-360dialog-signature`** header. Validate them with your existing webhook secret; no new secret or verification path is needed.
## Delivery receipts
Delivery and read receipts for the agent's messages are **bizai-tagged** (the same `originator: bizai` marker). They arrive on your webhook already, so you can track delivery of agent messages without any extra setup.
# API Ref
# Onboarding
Endpoints for onboarding a Business Agent and managing its allowlist and settings
# List allowlist entries
Retrieve a list of all allowlisted consumer phone numbers for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Onboarding","description":"Endpoints for onboarding a Business Agent and managing its allowlist and settings"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"onboard.BizAIOmniChannelAllowlistResponse":{"description":"A single allowlist entry","properties":{"consumer_phone_number":{"description":"Consumer WhatsApp phone number in E.164 format","type":"string"},"id":{"description":"The unique identifier for this allowlist entry","type":"string"}},"type":"object"},"onboard.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/allowlist":{"get":{"description":"Retrieve a list of all allowlisted consumer phone numbers for the specified entity.","operationId":"get-agent-config-allowlist","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelAllowlistResponse"},"type":"array"}}},"description":"A list of all allowlist entries"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Server error"}},"summary":"List allowlist entries","tags":["Onboarding"]}}}}
```
# Add to allowlist
Add a consumer phone number to the allowlist for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Onboarding","description":"Endpoints for onboarding a Business Agent and managing its allowlist and settings"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"onboard.BizAIOmniChannelAllowlistRequest":{"description":"Request payload to add a consumer WhatsApp phone number to the allowlist","properties":{"consumer_phone_number":{"description":"Consumer WhatsApp phone number in E.164 format (e.g. +15551234567)","type":"string"}},"required":["consumer_phone_number"],"type":"object"},"onboard.BizAIOmniChannelAllowlistResponse":{"description":"A single allowlist entry","properties":{"consumer_phone_number":{"description":"Consumer WhatsApp phone number in E.164 format","type":"string"},"id":{"description":"The unique identifier for this allowlist entry","type":"string"}},"type":"object"},"onboard.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/allowlist":{"post":{"description":"Add a consumer phone number to the allowlist for the specified entity.","operationId":"post-agent-config-allowlist","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelAllowlistRequest","summary":"requestBody","description":"Consumer phone number to allowlist"}}},"description":"Consumer phone number to allowlist","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelAllowlistResponse"}}},"description":"The newly created allowlist entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Server error"}},"summary":"Add to allowlist","tags":["Onboarding"]}}}}
```
# Remove from allowlist
Remove a specific allowlist entry by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Onboarding","description":"Endpoints for onboarding a Business Agent and managing its allowlist and settings"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"onboard.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/allowlist/{entry_id}":{"delete":{"description":"Remove a specific allowlist entry by its ID.","operationId":"delete-agent-config-allowlist-entry","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the allowlist entry","in":"path","name":"entry_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Allowlist entry successfully deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Server error"}},"summary":"Remove from allowlist","tags":["Onboarding"]}}}}
```
# Get AI agent settings
Retrieve the current AI settings for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Onboarding","description":"Endpoints for onboarding a Business Agent and managing its allowlist and settings"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"onboard.BizAIOmniChannelSettingsResponse":{"description":"The AI agent settings for an entity","properties":{"agent_id":{"description":"Unique identifier for this agent configuration. Use this ID to target a specific agent in update or delete operations","type":"string"},"ai_audience":{"description":"Controls which consumers the AI agent responds to. EVERYONE = all consumers (default), ALLOWLISTED_ONLY = only phone numbers in the allowlist. Null for non-WhatsApp entities.","enum":["ALLOWLISTED_ONLY","EVERYONE"],"type":"string"},"channel":{"description":"The channel/platform these settings apply to","enum":["email","instagram","line","messenger","sms","tiktok","unknown","webchat","whatsapp"],"type":"string"},"followup":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsFollowup"},"handoff":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsHandoff"},"rollout":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsRollout"}},"required":["agent_id","channel","rollout"],"type":"object"},"onboard.BizAIOmniChannelSettingsFollowup":{"description":"Settings for following up with an inactive user. Null if not configured","properties":{"enabled":{"description":"Whether followup is enabled. true to enable, false to disable","type":"boolean"},"followup_interval_in_seconds":{"description":"The time in seconds of user inactivity before the followup message is sent. Setting to 0 will disable followup","enum":[0,300,900,1800,3600,7200,28800,86400],"type":"integer"},"message":{"description":"The message sent to follow up with the user after inactivity","type":"string"}},"required":["enabled"],"type":"object"},"onboard.BizAIOmniChannelSettingsHandoff":{"description":"Settings for handing over the conversation to a human agent. Null if not configured","properties":{"enabled":{"description":"Whether handoff to a human agent is enabled. true to enable, false to disable","type":"boolean"},"message":{"description":"The message displayed to the user when a handoff to a human agent occurs","type":"string"}},"required":["enabled"],"type":"object"},"onboard.BizAIOmniChannelSettingsRollout":{"description":"Rollout configuration for the AI agent, containing the enabled flag and future gradual rollout fields","properties":{"enabled":{"description":"Whether the AI agent is currently enabled. true for on, false for off","type":"boolean"}},"required":["enabled"],"type":"object"},"onboard.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/settings":{"get":{"description":"Retrieve the current AI settings for the specified entity.","operationId":"get-agent-config-settings","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"Optional agent ID. When provided, returns the specific agent configuration. When absent, returns all settings for the given channel.","in":"query","name":"agent_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsResponse"},"type":"array"}}},"description":"The AI settings for the entity"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Server error"}},"summary":"Get AI agent settings","tags":["Onboarding"]}}}}
```
# Update AI agent settings
Create or fully replace the AI settings for the specified entity. All fields must be provided for a complete replacement. Note that disabling the agent will make the AI stop responding to all threads. Re-enabling it will make the AI start responding to new threads only.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Onboarding","description":"Endpoints for onboarding a Business Agent and managing its allowlist and settings"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"onboard.BizAIOmniChannelSettingsRequest":{"description":"Create or fully replace the AI agent settings for an entity","properties":{"ai_audience":{"description":"Controls which consumers the AI agent responds to. EVERYONE = all consumers (default), ALLOWLISTED_ONLY = only phone numbers in the allowlist. Only supported for WhatsApp entities.","enum":["ALLOWLISTED_ONLY","EVERYONE"],"type":"string"},"followup":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsFollowup"},"handoff":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsHandoff"},"rollout":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsRollout"}},"type":"object"},"onboard.BizAIOmniChannelSettingsFollowup":{"description":"Settings for following up with an inactive user. Null if not configured","properties":{"enabled":{"description":"Whether followup is enabled. true to enable, false to disable","type":"boolean"},"followup_interval_in_seconds":{"description":"The time in seconds of user inactivity before the followup message is sent. Setting to 0 will disable followup","enum":[0,300,900,1800,3600,7200,28800,86400],"type":"integer"},"message":{"description":"The message sent to follow up with the user after inactivity","type":"string"}},"required":["enabled"],"type":"object"},"onboard.BizAIOmniChannelSettingsHandoff":{"description":"Settings for handing over the conversation to a human agent. Null if not configured","properties":{"enabled":{"description":"Whether handoff to a human agent is enabled. true to enable, false to disable","type":"boolean"},"message":{"description":"The message displayed to the user when a handoff to a human agent occurs","type":"string"}},"required":["enabled"],"type":"object"},"onboard.BizAIOmniChannelSettingsRollout":{"description":"Rollout configuration for the AI agent, containing the enabled flag and future gradual rollout fields","properties":{"enabled":{"description":"Whether the AI agent is currently enabled. true for on, false for off","type":"boolean"}},"required":["enabled"],"type":"object"},"onboard.BizAIOmniChannelSettingsResponse":{"description":"The AI agent settings for an entity","properties":{"agent_id":{"description":"Unique identifier for this agent configuration. Use this ID to target a specific agent in update or delete operations","type":"string"},"ai_audience":{"description":"Controls which consumers the AI agent responds to. EVERYONE = all consumers (default), ALLOWLISTED_ONLY = only phone numbers in the allowlist. Null for non-WhatsApp entities.","enum":["ALLOWLISTED_ONLY","EVERYONE"],"type":"string"},"channel":{"description":"The channel/platform these settings apply to","enum":["email","instagram","line","messenger","sms","tiktok","unknown","webchat","whatsapp"],"type":"string"},"followup":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsFollowup"},"handoff":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsHandoff"},"rollout":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsRollout"}},"required":["agent_id","channel","rollout"],"type":"object"},"onboard.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/settings":{"put":{"description":"Create or fully replace the AI settings for the specified entity. All fields must be provided for a complete replacement. Note that disabling the agent will make the AI stop responding to all threads. Re-enabling it will make the AI start responding to new threads only.","operationId":"put-agent-config-settings","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"Optional agent ID. When provided, updates the specific agent configuration. When absent, uses create-or-fetch behavior.","in":"query","name":"agent_id","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsRequest","summary":"requestBody","description":"AI agent settings to create or replace"}}},"description":"AI agent settings to create or replace","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelSettingsResponse"}}},"description":"The updated AI settings for the entity"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Server error"}},"summary":"Update AI agent settings","tags":["Onboarding"]}}}}
```
# Get agent eligibility
Check whether the business AI agent is eligible for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Onboarding","description":"Endpoints for onboarding a Business Agent and managing its allowlist and settings"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"onboard.BizAIOmniChannelEligibilityResponse":{"description":"Eligibility result for the entity","properties":{"is_eligible":{"description":"Whether the entity is eligible for the business AI agent. true for eligible, false for not eligible","type":"boolean"}},"type":"object"},"onboard.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_eligibility":{"get":{"description":"Check whether the business AI agent is eligible for the specified entity.","operationId":"get-agent-eligibility","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelEligibilityResponse"}}},"description":"Eligibility result for the entity"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Server error"}},"summary":"Get agent eligibility","tags":["Onboarding"]}}}}
```
# Create an onboarding session
Trigger AI agent onboarding for the specified entity and channel. Creates the necessary entities and schedules async jobs for data preparation.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Onboarding","description":"Endpoints for onboarding a Business Agent and managing its allowlist and settings"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"onboard.BizAIOmniChannelOnboardingResponse":{"description":"Result of triggering AI agent onboarding","properties":{"agent_id":{"description":"The ID of the agent settings entity","type":"string"}},"type":"object"},"onboard.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_onboarding":{"post":{"description":"Trigger AI agent onboarding for the specified entity and channel. Creates the necessary entities and schedules async jobs for data preparation.","operationId":"post-agent-onboarding","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The channel to onboard the AI agent for","in":"query","name":"channel","required":true,"schema":{"enum":["email","instagram","line","messenger","sms","tiktok","unknown","webchat","whatsapp"],"type":"string"}}],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelOnboardingResponse"}}},"description":"Onboarding triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Server error"}},"summary":"Create an onboarding session","tags":["Onboarding"]}}}}
```
# Delete the agent
Remove the Meta Business agent from the WhatsApp phone number. Deletes the agent configuration and, when the last agent on the account is removed, disconnects the integration.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Onboarding","description":"Endpoints for onboarding a Business Agent and managing its allowlist and settings"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"onboard.BizAIOmniChannelDeleteAgentResponse":{"description":"Result of removing the Meta Business agent from the phone number","properties":{"deleted_agent_id":{"description":"The ID of the AI agent settings that was removed, or null if there was nothing to remove","type":"string"}},"type":"object"},"onboard.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/delete_agent":{"delete":{"description":"Remove the Meta Business agent from the WhatsApp phone number. Deletes the agent configuration and, when the last agent on the account is removed, disconnects the integration.","operationId":"delete-agent","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.BizAIOmniChannelDeleteAgentResponse"}}},"description":"The agent was removed, or there was nothing to remove"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Forbidden"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/onboard.StandardError"}}},"description":"Server error"}},"summary":"Delete the agent","tags":["Onboarding"]}}}}
```
# Knowledge Business Info
Endpoints for managing the agent's business information
# Get business information
Retrieve the current business information for the specified entity. Returns empty/default values if none has been configured.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Business Info","description":"Endpoints for managing the agent's business information"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_bi.BizAIOmniChannelKnowledgeBusinessInfoResponse":{"description":"The business information configured for an entity","properties":{"business_description":{"description":"General information about the business","type":"string"},"contact_info":{"$ref":"#/components/schemas/knowledge_bi.BizAIOmniChannelKnowledgeContactInfo"},"delivery_and_shipping":{"description":"Details about delivery and shipping","type":"string"},"payment_method":{"description":"Accepted payment methods","type":"string"},"purchase_info":{"description":"Information about how to make a purchase","type":"string"},"return_policy":{"description":"The company return policy","type":"string"}},"type":"object"},"knowledge_bi.BizAIOmniChannelKnowledgeContactInfo":{"description":"Contact and location details for the business. Null if not configured","properties":{"address":{"description":"Physical address of the business","type":"string"},"email":{"description":"Business email address","type":"string"},"hours_of_operation":{"description":"Business hours of operation","type":"string"}},"type":"object"},"knowledge_bi.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/business_info":{"get":{"description":"Retrieve the current business information for the specified entity. Returns empty/default values if none has been configured.","operationId":"get-agent-config-business-info","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.BizAIOmniChannelKnowledgeBusinessInfoResponse"}}},"description":"The current business information for the entity"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Server error"}},"summary":"Get business information","tags":["Knowledge - Business Info"]}}}}
```
# Create or replace business information
Create or fully replace the business information for the specified entity. All provided fields will overwrite existing values.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Business Info","description":"Endpoints for managing the agent's business information"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_bi.BizAIOmniChannelKnowledgeBusinessInfoRequest":{"description":"Create or fully replace the business information for an entity","properties":{"business_description":{"description":"General information about the business","type":"string"},"contact_info":{"$ref":"#/components/schemas/knowledge_bi.BizAIOmniChannelKnowledgeContactInfo"},"delivery_and_shipping":{"description":"Details about delivery and shipping","type":"string"},"payment_method":{"description":"Accepted payment methods","type":"string"},"purchase_info":{"description":"Information about how to make a purchase","type":"string"},"return_policy":{"description":"The company return policy","type":"string"}},"type":"object"},"knowledge_bi.BizAIOmniChannelKnowledgeContactInfo":{"description":"Contact and location details for the business. Null if not configured","properties":{"address":{"description":"Physical address of the business","type":"string"},"email":{"description":"Business email address","type":"string"},"hours_of_operation":{"description":"Business hours of operation","type":"string"}},"type":"object"},"knowledge_bi.BizAIOmniChannelKnowledgeBusinessInfoResponse":{"description":"The business information configured for an entity","properties":{"business_description":{"description":"General information about the business","type":"string"},"contact_info":{"$ref":"#/components/schemas/knowledge_bi.BizAIOmniChannelKnowledgeContactInfo"},"delivery_and_shipping":{"description":"Details about delivery and shipping","type":"string"},"payment_method":{"description":"Accepted payment methods","type":"string"},"purchase_info":{"description":"Information about how to make a purchase","type":"string"},"return_policy":{"description":"The company return policy","type":"string"}},"type":"object"},"knowledge_bi.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/business_info":{"put":{"description":"Create or fully replace the business information for the specified entity. All provided fields will overwrite existing values.","operationId":"put-agent-config-business-info","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.BizAIOmniChannelKnowledgeBusinessInfoRequest","summary":"requestBody","description":"Business information to create or replace"}}},"description":"Business information to create or replace","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.BizAIOmniChannelKnowledgeBusinessInfoResponse"}}},"description":"The updated business information for the entity"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Server error"}},"summary":"Create or replace business information","tags":["Knowledge - Business Info"]}}}}
```
# Reset business information to defaults
Reset the business information for the specified entity to default values. Returns the default (empty) business info object.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Business Info","description":"Endpoints for managing the agent's business information"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_bi.BizAIOmniChannelKnowledgeBusinessInfoResponse":{"description":"The business information configured for an entity","properties":{"business_description":{"description":"General information about the business","type":"string"},"contact_info":{"$ref":"#/components/schemas/knowledge_bi.BizAIOmniChannelKnowledgeContactInfo"},"delivery_and_shipping":{"description":"Details about delivery and shipping","type":"string"},"payment_method":{"description":"Accepted payment methods","type":"string"},"purchase_info":{"description":"Information about how to make a purchase","type":"string"},"return_policy":{"description":"The company return policy","type":"string"}},"type":"object"},"knowledge_bi.BizAIOmniChannelKnowledgeContactInfo":{"description":"Contact and location details for the business. Null if not configured","properties":{"address":{"description":"Physical address of the business","type":"string"},"email":{"description":"Business email address","type":"string"},"hours_of_operation":{"description":"Business hours of operation","type":"string"}},"type":"object"},"knowledge_bi.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/business_info":{"delete":{"description":"Reset the business information for the specified entity to default values. Returns the default (empty) business info object.","operationId":"delete-agent-config-business-info","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.BizAIOmniChannelKnowledgeBusinessInfoResponse"}}},"description":"The default business information after reset"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_bi.StandardError"}}},"description":"Server error"}},"summary":"Reset business information to defaults","tags":["Knowledge - Business Info"]}}}}
```
# Knowledge FAQ
Endpoints for managing the agent's FAQ entries
# List FAQs
Retrieve a list of all FAQ entries for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - FAQ","description":"Endpoints for managing the agent's FAQ entries"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_faq.BizAIOmniChannelKnowledgeFAQResponse":{"description":"A single FAQ entry","properties":{"answer":{"description":"The FAQ answer text","type":"string"},"created_at":{"description":"The timestamp when the FAQ was created","type":"integer"},"id":{"description":"The unique identifier for this FAQ entry","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"Key-value metadata associated with this FAQ entry","type":"object"},"question":{"description":"The FAQ question text","type":"string"}},"required":["answer","id","question"],"type":"object"},"knowledge_faq.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/faq":{"get":{"description":"Retrieve a list of all FAQ entries for the specified entity.","operationId":"get-agent-config-faq","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/knowledge_faq.BizAIOmniChannelKnowledgeFAQResponse"},"type":"array"}}},"description":"A list of all FAQ entries"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Server error"}},"summary":"List FAQs","tags":["Knowledge - FAQ"]}}}}
```
# Create an FAQ
Create a new FAQ entry for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - FAQ","description":"Endpoints for managing the agent's FAQ entries"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_faq.BizAIOmniChannelKnowledgeFAQRequest":{"description":"Create or update an FAQ entry","properties":{"answer":{"description":"The FAQ answer text. Keep answers factual, concise, and self-contained.","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"Key-value metadata associated with this FAQ entry","type":"object"},"question":{"description":"The FAQ question text. Write it as a natural question a customer would ask. Each FAQ should address a single, specific topic.","type":"string"}},"required":["answer","question"],"type":"object"},"knowledge_faq.BizAIOmniChannelKnowledgeFAQResponse":{"description":"A single FAQ entry","properties":{"answer":{"description":"The FAQ answer text","type":"string"},"created_at":{"description":"The timestamp when the FAQ was created","type":"integer"},"id":{"description":"The unique identifier for this FAQ entry","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"Key-value metadata associated with this FAQ entry","type":"object"},"question":{"description":"The FAQ question text","type":"string"}},"required":["answer","id","question"],"type":"object"},"knowledge_faq.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/faq":{"post":{"description":"Create a new FAQ entry for the specified entity.","operationId":"post-agent-config-faq","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.BizAIOmniChannelKnowledgeFAQRequest","summary":"requestBody","description":"FAQ entry to create"}}},"description":"FAQ entry to create","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.BizAIOmniChannelKnowledgeFAQResponse"}}},"description":"The newly created FAQ entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Server error"}},"summary":"Create an FAQ","tags":["Knowledge - FAQ"]}}}}
```
# Get an FAQ
Retrieve a specific FAQ entry by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - FAQ","description":"Endpoints for managing the agent's FAQ entries"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_faq.BizAIOmniChannelKnowledgeFAQResponse":{"description":"A single FAQ entry","properties":{"answer":{"description":"The FAQ answer text","type":"string"},"created_at":{"description":"The timestamp when the FAQ was created","type":"integer"},"id":{"description":"The unique identifier for this FAQ entry","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"Key-value metadata associated with this FAQ entry","type":"object"},"question":{"description":"The FAQ question text","type":"string"}},"required":["answer","id","question"],"type":"object"},"knowledge_faq.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/faq/{faq_id}":{"get":{"description":"Retrieve a specific FAQ entry by its ID.","operationId":"get-agent-config-faq-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the FAQ entry","in":"path","name":"faq_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.BizAIOmniChannelKnowledgeFAQResponse"}}},"description":"The requested FAQ entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Server error"}},"summary":"Get an FAQ","tags":["Knowledge - FAQ"]}}}}
```
# Update an FAQ
Update a specific FAQ entry by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - FAQ","description":"Endpoints for managing the agent's FAQ entries"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_faq.BizAIOmniChannelKnowledgeFAQRequest":{"description":"Create or update an FAQ entry","properties":{"answer":{"description":"The FAQ answer text. Keep answers factual, concise, and self-contained.","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"Key-value metadata associated with this FAQ entry","type":"object"},"question":{"description":"The FAQ question text. Write it as a natural question a customer would ask. Each FAQ should address a single, specific topic.","type":"string"}},"required":["answer","question"],"type":"object"},"knowledge_faq.BizAIOmniChannelKnowledgeFAQResponse":{"description":"A single FAQ entry","properties":{"answer":{"description":"The FAQ answer text","type":"string"},"created_at":{"description":"The timestamp when the FAQ was created","type":"integer"},"id":{"description":"The unique identifier for this FAQ entry","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"Key-value metadata associated with this FAQ entry","type":"object"},"question":{"description":"The FAQ question text","type":"string"}},"required":["answer","id","question"],"type":"object"},"knowledge_faq.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/faq/{faq_id}":{"put":{"description":"Update a specific FAQ entry by its ID.","operationId":"put-agent-config-faq-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the FAQ entry","in":"path","name":"faq_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.BizAIOmniChannelKnowledgeFAQRequest","summary":"requestBody","description":"Updated FAQ entry"}}},"description":"Updated FAQ entry","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.BizAIOmniChannelKnowledgeFAQResponse"}}},"description":"The updated FAQ entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Server error"}},"summary":"Update an FAQ","tags":["Knowledge - FAQ"]}}}}
```
# Delete an FAQ
Delete a specific FAQ entry by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - FAQ","description":"Endpoints for managing the agent's FAQ entries"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_faq.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/faq/{faq_id}":{"delete":{"description":"Delete a specific FAQ entry by its ID.","operationId":"delete-agent-config-faq-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the FAQ entry","in":"path","name":"faq_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"FAQ entry successfully deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_faq.StandardError"}}},"description":"Server error"}},"summary":"Delete an FAQ","tags":["Knowledge - FAQ"]}}}}
```
# Knowledge Files
Endpoints for managing the agent's knowledge base files
# List knowledge files
Retrieve a list of all files in the AI agent knowledge base for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Files","description":"Endpoints for managing the agent's knowledge base files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_files.BizAIOmniChannelKnowledgeFileResponse":{"description":"Metadata of a knowledge base file","properties":{"file_name":{"description":"The name of the file","type":"string"},"id":{"description":"The unique identifier for this file","type":"string"}},"required":["file_name","id"],"type":"object"},"knowledge_files.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/files":{"get":{"description":"Retrieve a list of all files in the AI agent knowledge base for the specified entity.","operationId":"get-agent-config-files","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/knowledge_files.BizAIOmniChannelKnowledgeFileResponse"},"type":"array"}}},"description":"A list of all knowledge base files"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Server error"}},"summary":"List knowledge files","tags":["Knowledge - Files"]}}}}
```
# Upload a knowledge file
Upload a new file to the AI agent knowledge base for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Files","description":"Endpoints for managing the agent's knowledge base files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_files.BizAIOmniChannelKnowledgeFileResponse":{"description":"Metadata of a knowledge base file","properties":{"file_name":{"description":"The name of the file","type":"string"},"id":{"description":"The unique identifier for this file","type":"string"}},"required":["file_name","id"],"type":"object"},"knowledge_files.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/files":{"post":{"description":"Upload a new file to the AI agent knowledge base for the specified entity.","operationId":"post-agent-config-files","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The file to upload. Max 100000000 bytes. Supported: .pdf, .doc, .docx, .png, .jpg, .jpeg, .csv (if CSV extraction enabled), .xlsx (if XLSX extraction enabled)","format":"binary","type":"string"},"file_name":{"description":"The name of the file being uploaded","type":"string"}},"required":["file_name","file"],"type":"object"}}},"description":"The name of the file being uploaded","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.BizAIOmniChannelKnowledgeFileResponse"}}},"description":"The newly uploaded file metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Server error"}},"summary":"Upload a knowledge file","tags":["Knowledge - Files"]}}}}
```
# Get a knowledge file
Retrieve a specific file's metadata by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Files","description":"Endpoints for managing the agent's knowledge base files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_files.BizAIOmniChannelKnowledgeFileResponse":{"description":"Metadata of a knowledge base file","properties":{"file_name":{"description":"The name of the file","type":"string"},"id":{"description":"The unique identifier for this file","type":"string"}},"required":["file_name","id"],"type":"object"},"knowledge_files.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/files/{file_id}":{"get":{"description":"Retrieve a specific file's metadata by its ID.","operationId":"get-agent-config-files-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the file","in":"path","name":"file_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.BizAIOmniChannelKnowledgeFileResponse"}}},"description":"The requested file metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Server error"}},"summary":"Get a knowledge file","tags":["Knowledge - Files"]}}}}
```
# Delete a knowledge file
Delete a specific file from the knowledge base by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Files","description":"Endpoints for managing the agent's knowledge base files"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_files.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/files/{file_id}":{"delete":{"description":"Delete a specific file from the knowledge base by its ID.","operationId":"delete-agent-config-files-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the file","in":"path","name":"file_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"File successfully deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_files.StandardError"}}},"description":"Server error"}},"summary":"Delete a knowledge file","tags":["Knowledge - Files"]}}}}
```
# Knowledge Websites
Endpoints for managing the agent's crawled knowledge websites
# List knowledge websites
Retrieve a list of all website URLs configured for AI agent knowledge crawling.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Websites","description":"Endpoints for managing the agent's crawled knowledge websites"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_websites.BizAIKnowledgeWebsiteResponse":{"description":"A single website crawl entry","properties":{"crawl_status":{"description":"The current status of the crawl (e.g., \"pending\", \"in_progress\", \"completed\", \"failed\")","type":"string"},"created_at":{"description":"The timestamp when the website entry was created","type":"integer"},"id":{"description":"The unique identifier for this website crawl entry","type":"string"},"last_crawled_at":{"description":"The timestamp when the website was last successfully crawled","type":"integer"},"pages_crawled":{"description":"The number of pages successfully crawled","type":"integer"},"url":{"description":"The URL of the website being crawled","type":"string"}},"required":["id","url"],"type":"object"},"knowledge_websites.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/websites":{"get":{"description":"Retrieve a list of all website URLs configured for AI agent knowledge crawling.","operationId":"get-agent-config-websites","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/knowledge_websites.BizAIKnowledgeWebsiteResponse"},"type":"array"}}},"description":"A list of all website crawl entries"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Server error"}},"summary":"List knowledge websites","tags":["Knowledge - Websites"]}}}}
```
# Add a knowledge website
Add a new website URL for the AI agent to crawl and ingest into its knowledge base.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Websites","description":"Endpoints for managing the agent's crawled knowledge websites"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_websites.BizAIKnowledgeWebsiteRequest":{"description":"Add or update a website crawl entry","properties":{"url":{"description":"The URL of the website to crawl","type":"string"}},"required":["url"],"type":"object"},"knowledge_websites.BizAIKnowledgeWebsiteResponse":{"description":"A single website crawl entry","properties":{"crawl_status":{"description":"The current status of the crawl (e.g., \"pending\", \"in_progress\", \"completed\", \"failed\")","type":"string"},"created_at":{"description":"The timestamp when the website entry was created","type":"integer"},"id":{"description":"The unique identifier for this website crawl entry","type":"string"},"last_crawled_at":{"description":"The timestamp when the website was last successfully crawled","type":"integer"},"pages_crawled":{"description":"The number of pages successfully crawled","type":"integer"},"url":{"description":"The URL of the website being crawled","type":"string"}},"required":["id","url"],"type":"object"},"knowledge_websites.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/websites":{"post":{"description":"Add a new website URL for the AI agent to crawl and ingest into its knowledge base.","operationId":"post-agent-config-websites","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.BizAIKnowledgeWebsiteRequest","summary":"requestBody","description":"Website to add"}}},"description":"Website to add","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.BizAIKnowledgeWebsiteResponse"}}},"description":"The newly created website crawl entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Forbidden"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Server error"}},"summary":"Add a knowledge website","tags":["Knowledge - Websites"]}}}}
```
# Get a knowledge website
Retrieve a specific website crawl entry by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Websites","description":"Endpoints for managing the agent's crawled knowledge websites"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_websites.BizAIKnowledgeWebsiteResponse":{"description":"A single website crawl entry","properties":{"crawl_status":{"description":"The current status of the crawl (e.g., \"pending\", \"in_progress\", \"completed\", \"failed\")","type":"string"},"created_at":{"description":"The timestamp when the website entry was created","type":"integer"},"id":{"description":"The unique identifier for this website crawl entry","type":"string"},"last_crawled_at":{"description":"The timestamp when the website was last successfully crawled","type":"integer"},"pages_crawled":{"description":"The number of pages successfully crawled","type":"integer"},"url":{"description":"The URL of the website being crawled","type":"string"}},"required":["id","url"],"type":"object"},"knowledge_websites.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/websites/{website_id}":{"get":{"description":"Retrieve a specific website crawl entry by its ID.","operationId":"get-agent-config-websites-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the website crawl entry","in":"path","name":"website_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.BizAIKnowledgeWebsiteResponse"}}},"description":"The requested website crawl entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Server error"}},"summary":"Get a knowledge website","tags":["Knowledge - Websites"]}}}}
```
# Update a knowledge website
Update a specific website crawl entry by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Websites","description":"Endpoints for managing the agent's crawled knowledge websites"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_websites.BizAIKnowledgeWebsiteRequest":{"description":"Add or update a website crawl entry","properties":{"url":{"description":"The URL of the website to crawl","type":"string"}},"required":["url"],"type":"object"},"knowledge_websites.BizAIKnowledgeWebsiteResponse":{"description":"A single website crawl entry","properties":{"crawl_status":{"description":"The current status of the crawl (e.g., \"pending\", \"in_progress\", \"completed\", \"failed\")","type":"string"},"created_at":{"description":"The timestamp when the website entry was created","type":"integer"},"id":{"description":"The unique identifier for this website crawl entry","type":"string"},"last_crawled_at":{"description":"The timestamp when the website was last successfully crawled","type":"integer"},"pages_crawled":{"description":"The number of pages successfully crawled","type":"integer"},"url":{"description":"The URL of the website being crawled","type":"string"}},"required":["id","url"],"type":"object"},"knowledge_websites.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/websites/{website_id}":{"put":{"description":"Update a specific website crawl entry by its ID.","operationId":"put-agent-config-websites-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the website crawl entry","in":"path","name":"website_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.BizAIKnowledgeWebsiteRequest","summary":"requestBody","description":"Updated website"}}},"description":"Updated website","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.BizAIKnowledgeWebsiteResponse"}}},"description":"The updated website crawl entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Server error"}},"summary":"Update a knowledge website","tags":["Knowledge - Websites"]}}}}
```
# Delete a knowledge website
Delete a specific website crawl entry from the knowledge base by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Websites","description":"Endpoints for managing the agent's crawled knowledge websites"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_websites.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/websites/{website_id}":{"delete":{"description":"Delete a specific website crawl entry from the knowledge base by its ID.","operationId":"delete-agent-config-websites-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the website crawl entry","in":"path","name":"website_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Website crawl entry successfully deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_websites.StandardError"}}},"description":"Server error"}},"summary":"Delete a knowledge website","tags":["Knowledge - Websites"]}}}}
```
# Knowledge Skills
Endpoints for managing the agent's AI skills
# List skills
Retrieve a list of all AI skills for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Skills","description":"Endpoints for managing the agent's AI skills"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_skills.BizAIOmniChannelSkillsResponse":{"description":"A single AI skill","properties":{"channel":{"description":"The channel/platform this skill applies to","enum":["email","instagram","line","messenger","sms","tiktok","unknown","webchat","whatsapp"],"type":"string"},"created_at":{"description":"The timestamp when the skill was created","type":"integer"},"description":{"description":"A description telling the AI when to apply this skill","type":"string"},"id":{"description":"A unique identifier for the skill","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"A map of key-value pairs for additional metadata","type":"object"},"skill":{"description":"The body containing the actual instructions for the AI. Has no specific restrictions on structure or content.","type":"string"},"title":{"description":"An optional, human-readable name for the skill","type":"string"}},"required":["channel","id","skill"],"type":"object"},"knowledge_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/skills":{"get":{"description":"Retrieve a list of all AI skills for the specified entity.","operationId":"get-agent-config-skills","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"Optional settings ID. When provided, returns skills for the specified settings. When absent, returns skills for the most recently created settings for the given channel.","in":"query","name":"agent_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/knowledge_skills.BizAIOmniChannelSkillsResponse"},"type":"array"}}},"description":"A list of all skills"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Server error"}},"summary":"List skills","tags":["Knowledge - Skills"]}}}}
```
# Create a skill
Create a new AI skill for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Skills","description":"Endpoints for managing the agent's AI skills"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_skills.BizAIOmniChannelSkillsRequest":{"description":"Create or update an AI skill","properties":{"description":{"description":"A description telling the AI when to apply this skill. Max 1024 characters. Be specific about the trigger or context.","type":"string"},"skill":{"description":"The body containing the actual instructions for the AI. Max 20000 characters. Write clear, non-conflicting directives.","type":"string"},"title":{"description":"A human-readable name for the skill. Max 64 characters. Must contain only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen.","type":"string"}},"type":"object"},"knowledge_skills.BizAIOmniChannelSkillsResponse":{"description":"A single AI skill","properties":{"channel":{"description":"The channel/platform this skill applies to","enum":["email","instagram","line","messenger","sms","tiktok","unknown","webchat","whatsapp"],"type":"string"},"created_at":{"description":"The timestamp when the skill was created","type":"integer"},"description":{"description":"A description telling the AI when to apply this skill","type":"string"},"id":{"description":"A unique identifier for the skill","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"A map of key-value pairs for additional metadata","type":"object"},"skill":{"description":"The body containing the actual instructions for the AI. Has no specific restrictions on structure or content.","type":"string"},"title":{"description":"An optional, human-readable name for the skill","type":"string"}},"required":["channel","id","skill"],"type":"object"},"knowledge_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/skills":{"post":{"description":"Create a new AI skill for the specified entity.","operationId":"post-agent-config-skills","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"Optional settings ID. When provided, creates the skill under the specified settings. When absent, uses the most recently created settings for the given channel.","in":"query","name":"agent_id","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.BizAIOmniChannelSkillsRequest","summary":"requestBody","description":"Skill to create"}}},"description":"Skill to create","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.BizAIOmniChannelSkillsResponse"}}},"description":"The newly created skill"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Server error"}},"summary":"Create a skill","tags":["Knowledge - Skills"]}}}}
```
# Get a skill
Retrieve a specific AI skill by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Skills","description":"Endpoints for managing the agent's AI skills"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_skills.BizAIOmniChannelSkillsResponse":{"description":"A single AI skill","properties":{"channel":{"description":"The channel/platform this skill applies to","enum":["email","instagram","line","messenger","sms","tiktok","unknown","webchat","whatsapp"],"type":"string"},"created_at":{"description":"The timestamp when the skill was created","type":"integer"},"description":{"description":"A description telling the AI when to apply this skill","type":"string"},"id":{"description":"A unique identifier for the skill","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"A map of key-value pairs for additional metadata","type":"object"},"skill":{"description":"The body containing the actual instructions for the AI. Has no specific restrictions on structure or content.","type":"string"},"title":{"description":"An optional, human-readable name for the skill","type":"string"}},"required":["channel","id","skill"],"type":"object"},"knowledge_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/skills/{skill_id}":{"get":{"description":"Retrieve a specific AI skill by its ID.","operationId":"get-agent-config-skills-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier (UUID) of the skill","in":"path","name":"skill_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.BizAIOmniChannelSkillsResponse"}}},"description":"The requested skill"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Server error"}},"summary":"Get a skill","tags":["Knowledge - Skills"]}}}}
```
# Update a skill
Update a specific AI skill by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Skills","description":"Endpoints for managing the agent's AI skills"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_skills.BizAIOmniChannelSkillsRequest":{"description":"Create or update an AI skill","properties":{"description":{"description":"A description telling the AI when to apply this skill. Max 1024 characters. Be specific about the trigger or context.","type":"string"},"skill":{"description":"The body containing the actual instructions for the AI. Max 20000 characters. Write clear, non-conflicting directives.","type":"string"},"title":{"description":"A human-readable name for the skill. Max 64 characters. Must contain only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen.","type":"string"}},"type":"object"},"knowledge_skills.BizAIOmniChannelSkillsResponse":{"description":"A single AI skill","properties":{"channel":{"description":"The channel/platform this skill applies to","enum":["email","instagram","line","messenger","sms","tiktok","unknown","webchat","whatsapp"],"type":"string"},"created_at":{"description":"The timestamp when the skill was created","type":"integer"},"description":{"description":"A description telling the AI when to apply this skill","type":"string"},"id":{"description":"A unique identifier for the skill","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"A map of key-value pairs for additional metadata","type":"object"},"skill":{"description":"The body containing the actual instructions for the AI. Has no specific restrictions on structure or content.","type":"string"},"title":{"description":"An optional, human-readable name for the skill","type":"string"}},"required":["channel","id","skill"],"type":"object"},"knowledge_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/skills/{skill_id}":{"put":{"description":"Update a specific AI skill by its ID.","operationId":"put-agent-config-skills-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier (UUID) of the skill","in":"path","name":"skill_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.BizAIOmniChannelSkillsRequest","summary":"requestBody","description":"Updated skill"}}},"description":"Updated skill","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.BizAIOmniChannelSkillsResponse"}}},"description":"The updated skill"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Server error"}},"summary":"Update a skill","tags":["Knowledge - Skills"]}}}}
```
# Delete a skill
Delete a specific AI skill by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Skills","description":"Endpoints for managing the agent's AI skills"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_config/skills/{skill_id}":{"delete":{"description":"Delete a specific AI skill by its ID.","operationId":"delete-agent-config-skills-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier (UUID) of the skill","in":"path","name":"skill_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Skill successfully deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_skills.StandardError"}}},"description":"Server error"}},"summary":"Delete a skill","tags":["Knowledge - Skills"]}}}}
```
# Knowledge Connectors
Endpoints for managing the agent's external API connectors
# List connectors
Retrieve a list of all connectors for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorResponse":{"description":"A single connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type for this connector","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external API","type":"string"},"connection_status":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus"},"connector_protocol":{"description":"Protocol used by this connector. Defaults to HTTP when omitted.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of the connector","type":"string"},"id":{"description":"The unique identifier for this connector","type":"string"},"mcp_tool_sync":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync"},"mtls_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig"},"name":{"description":"Display name of the connector","type":"string"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","connection_status","description","id","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorAuthConfig":{"description":"Authentication configuration for this connector","properties":{"api_key":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"},"oauth2_client_credentials":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig":{"description":"API key configuration. Provide only when auth_type is API_KEY.","properties":{"body_params":{"description":"API key fields to add as JSON body parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"headers":{"description":"API key fields to add as HTTP headers","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"query_params":{"description":"API key fields to add as query parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam":{"description":"A single API key field","properties":{"field_name":{"description":"Header, query parameter, or body field name","type":"string"},"prefix":{"description":"Optional value prefix, such as Bearer followed by a space","type":"string"},"value":{"description":"Secret value for this API key field","type":"string"}},"required":["field_name","value"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig":{"description":"OAuth 2.0 client credentials configuration. Provide only when auth_type is OAUTH2_CLIENT_CREDENTIALS.","properties":{"client_id":{"description":"OAuth client ID","type":"string"},"client_secret":{"description":"OAuth client secret","type":"string"},"scopes_to_request":{"description":"OAuth scopes to request","items":{"type":"string"},"type":"array","uniqueItems":false},"token_request_content_type":{"description":"Content type for token requests. Supports application/x-www-form-urlencoded and application/json. Defaults to application/x-www-form-urlencoded.","type":"string"},"token_url":{"description":"Token URL used to request OAuth access tokens","type":"string"}},"required":["client_id","client_secret","scopes_to_request","token_url"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus":{"description":"Connection status information","properties":{"error_message":{"description":"Error message if connection failed","type":"string"},"status":{"description":"Current connection status","enum":["PENDING_OAUTH","ACTIVE","EXPIRED","ERROR"],"type":"string"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync":{"description":"MCP tool discovery cache status. Null for HTTP connectors.","properties":{"fingerprint":{"description":"Fingerprint of the cached remote tool set","type":"string"},"last_attempted_at":{"description":"Unix timestamp of the latest refresh attempt","type":"integer"},"last_successful_at":{"description":"Unix timestamp of the latest successful refresh","type":"integer"},"status":{"description":"Current MCP tool refresh status","enum":["ERROR","PENDING","READY"],"type":"string"},"tool_count":{"description":"Number of cached remote MCP tools","type":"integer"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig":{"description":"mTLS certificate metadata and PEM content (private key is never exposed)","properties":{"ca_certificate":{"description":"PEM-encoded CA certificate chain (public, safe to expose)","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate (public, safe to expose)","type":"string"},"expires_at":{"description":"Unix timestamp of certificate expiry","type":"integer"},"fingerprint":{"description":"SHA-256 fingerprint of the certificate","type":"string"},"has_certificate":{"description":"Whether an mTLS certificate is configured","type":"boolean"},"subject":{"description":"Certificate subject DN","type":"string"}},"required":["has_certificate"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig":{"description":"Configuration for injecting user auth tokens into tool requests","properties":{"field_name":{"description":"Field name for the injected token (e.g. X-User-Token)","type":"string"},"location":{"description":"Where to inject the token","enum":["body","headers","path","query"],"type":"string"},"prefix":{"description":"Prefix for the token value (e.g. Bearer )","type":"string"}},"required":["field_name","location","prefix"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors":{"get":{"description":"Retrieve a list of all connectors for the specified entity.","operationId":"get-agent-connectors","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorResponse"},"type":"array"}}},"description":"A list of all connectors"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"List connectors","tags":["Knowledge - Connectors"]}}}}
```
# Create a connector
Create a new connector for the specified entity. The name must be unique among the connectors already created for this entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorRequest":{"description":"Create or update a connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type. Currently only OAUTH2_CLIENT_CREDENTIALS, API_KEY, and NONE are supported. Set auth_config.oauth2_client_credentials when this is OAUTH2_CLIENT_CREDENTIALS, set auth_config.api_key when this is API_KEY, and omit auth_config when this is NONE.","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external HTTP API or remote MCP server","type":"string"},"connector_protocol":{"description":"Connector protocol. Defaults to HTTP when omitted and cannot be changed after creation.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of what this connector integrates with and its purpose. The agent uses this to understand the connector capabilities, e.g. 'Connects to the Shopify API for managing customer orders, processing returns, and checking inventory availability.'","type":"string"},"name":{"description":"Display name of the connector. Use a name that clearly identifies the external service (e.g. Shopify_Order_Management, Salesforce_CRM). Must be unique among the connectors already created for this entity. Connector names must contain only letters, numbers, and underscores (regex: ^[A-Za-z0-9_]+$). They must not start or end with an underscore or contain consecutive underscores. Spaces, hyphens, dots, and accented characters are not allowed.","type":"string"},"requires_certificate":{"description":"Whether this connector requires an mTLS client certificate. When true, use the upsertCertificate endpoint to provide it.","type":"boolean"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","description","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorAuthConfig":{"description":"Authentication configuration for this connector","properties":{"api_key":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"},"oauth2_client_credentials":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig":{"description":"API key configuration. Provide only when auth_type is API_KEY.","properties":{"body_params":{"description":"API key fields to add as JSON body parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"headers":{"description":"API key fields to add as HTTP headers","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"query_params":{"description":"API key fields to add as query parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam":{"description":"A single API key field","properties":{"field_name":{"description":"Header, query parameter, or body field name","type":"string"},"prefix":{"description":"Optional value prefix, such as Bearer followed by a space","type":"string"},"value":{"description":"Secret value for this API key field","type":"string"}},"required":["field_name","value"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig":{"description":"OAuth 2.0 client credentials configuration. Provide only when auth_type is OAUTH2_CLIENT_CREDENTIALS.","properties":{"client_id":{"description":"OAuth client ID","type":"string"},"client_secret":{"description":"OAuth client secret","type":"string"},"scopes_to_request":{"description":"OAuth scopes to request","items":{"type":"string"},"type":"array","uniqueItems":false},"token_request_content_type":{"description":"Content type for token requests. Supports application/x-www-form-urlencoded and application/json. Defaults to application/x-www-form-urlencoded.","type":"string"},"token_url":{"description":"Token URL used to request OAuth access tokens","type":"string"}},"required":["client_id","client_secret","scopes_to_request","token_url"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig":{"description":"Configuration for injecting user auth tokens into tool requests","properties":{"field_name":{"description":"Field name for the injected token (e.g. X-User-Token)","type":"string"},"location":{"description":"Where to inject the token","enum":["body","headers","path","query"],"type":"string"},"prefix":{"description":"Prefix for the token value (e.g. Bearer )","type":"string"}},"required":["field_name","location","prefix"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorResponse":{"description":"A single connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type for this connector","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external API","type":"string"},"connection_status":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus"},"connector_protocol":{"description":"Protocol used by this connector. Defaults to HTTP when omitted.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of the connector","type":"string"},"id":{"description":"The unique identifier for this connector","type":"string"},"mcp_tool_sync":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync"},"mtls_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig"},"name":{"description":"Display name of the connector","type":"string"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","connection_status","description","id","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus":{"description":"Connection status information","properties":{"error_message":{"description":"Error message if connection failed","type":"string"},"status":{"description":"Current connection status","enum":["PENDING_OAUTH","ACTIVE","EXPIRED","ERROR"],"type":"string"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync":{"description":"MCP tool discovery cache status. Null for HTTP connectors.","properties":{"fingerprint":{"description":"Fingerprint of the cached remote tool set","type":"string"},"last_attempted_at":{"description":"Unix timestamp of the latest refresh attempt","type":"integer"},"last_successful_at":{"description":"Unix timestamp of the latest successful refresh","type":"integer"},"status":{"description":"Current MCP tool refresh status","enum":["ERROR","PENDING","READY"],"type":"string"},"tool_count":{"description":"Number of cached remote MCP tools","type":"integer"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig":{"description":"mTLS certificate metadata and PEM content (private key is never exposed)","properties":{"ca_certificate":{"description":"PEM-encoded CA certificate chain (public, safe to expose)","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate (public, safe to expose)","type":"string"},"expires_at":{"description":"Unix timestamp of certificate expiry","type":"integer"},"fingerprint":{"description":"SHA-256 fingerprint of the certificate","type":"string"},"has_certificate":{"description":"Whether an mTLS certificate is configured","type":"boolean"},"subject":{"description":"Certificate subject DN","type":"string"}},"required":["has_certificate"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors":{"post":{"description":"Create a new connector for the specified entity. The name must be unique among the connectors already created for this entity.","operationId":"post-agent-connectors","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorRequest","summary":"requestBody","description":"Connector to create"}}},"description":"Connector to create","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorResponse"}}},"description":"The newly created connector"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Conflict"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"Create a connector","tags":["Knowledge - Connectors"]}}}}
```
# Get a connector
Retrieve a specific connector by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorResponse":{"description":"A single connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type for this connector","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external API","type":"string"},"connection_status":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus"},"connector_protocol":{"description":"Protocol used by this connector. Defaults to HTTP when omitted.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of the connector","type":"string"},"id":{"description":"The unique identifier for this connector","type":"string"},"mcp_tool_sync":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync"},"mtls_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig"},"name":{"description":"Display name of the connector","type":"string"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","connection_status","description","id","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorAuthConfig":{"description":"Authentication configuration for this connector","properties":{"api_key":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"},"oauth2_client_credentials":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig":{"description":"API key configuration. Provide only when auth_type is API_KEY.","properties":{"body_params":{"description":"API key fields to add as JSON body parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"headers":{"description":"API key fields to add as HTTP headers","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"query_params":{"description":"API key fields to add as query parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam":{"description":"A single API key field","properties":{"field_name":{"description":"Header, query parameter, or body field name","type":"string"},"prefix":{"description":"Optional value prefix, such as Bearer followed by a space","type":"string"},"value":{"description":"Secret value for this API key field","type":"string"}},"required":["field_name","value"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig":{"description":"OAuth 2.0 client credentials configuration. Provide only when auth_type is OAUTH2_CLIENT_CREDENTIALS.","properties":{"client_id":{"description":"OAuth client ID","type":"string"},"client_secret":{"description":"OAuth client secret","type":"string"},"scopes_to_request":{"description":"OAuth scopes to request","items":{"type":"string"},"type":"array","uniqueItems":false},"token_request_content_type":{"description":"Content type for token requests. Supports application/x-www-form-urlencoded and application/json. Defaults to application/x-www-form-urlencoded.","type":"string"},"token_url":{"description":"Token URL used to request OAuth access tokens","type":"string"}},"required":["client_id","client_secret","scopes_to_request","token_url"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus":{"description":"Connection status information","properties":{"error_message":{"description":"Error message if connection failed","type":"string"},"status":{"description":"Current connection status","enum":["PENDING_OAUTH","ACTIVE","EXPIRED","ERROR"],"type":"string"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync":{"description":"MCP tool discovery cache status. Null for HTTP connectors.","properties":{"fingerprint":{"description":"Fingerprint of the cached remote tool set","type":"string"},"last_attempted_at":{"description":"Unix timestamp of the latest refresh attempt","type":"integer"},"last_successful_at":{"description":"Unix timestamp of the latest successful refresh","type":"integer"},"status":{"description":"Current MCP tool refresh status","enum":["ERROR","PENDING","READY"],"type":"string"},"tool_count":{"description":"Number of cached remote MCP tools","type":"integer"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig":{"description":"mTLS certificate metadata and PEM content (private key is never exposed)","properties":{"ca_certificate":{"description":"PEM-encoded CA certificate chain (public, safe to expose)","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate (public, safe to expose)","type":"string"},"expires_at":{"description":"Unix timestamp of certificate expiry","type":"integer"},"fingerprint":{"description":"SHA-256 fingerprint of the certificate","type":"string"},"has_certificate":{"description":"Whether an mTLS certificate is configured","type":"boolean"},"subject":{"description":"Certificate subject DN","type":"string"}},"required":["has_certificate"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig":{"description":"Configuration for injecting user auth tokens into tool requests","properties":{"field_name":{"description":"Field name for the injected token (e.g. X-User-Token)","type":"string"},"location":{"description":"Where to inject the token","enum":["body","headers","path","query"],"type":"string"},"prefix":{"description":"Prefix for the token value (e.g. Bearer )","type":"string"}},"required":["field_name","location","prefix"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}":{"get":{"description":"Retrieve a specific connector by its ID.","operationId":"get-agent-connectors-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorResponse"}}},"description":"The requested connector"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"Get a connector","tags":["Knowledge - Connectors"]}}}}
```
# Update a connector
Update a specific connector by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorRequest":{"description":"Create or update a connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type. Currently only OAUTH2_CLIENT_CREDENTIALS, API_KEY, and NONE are supported. Set auth_config.oauth2_client_credentials when this is OAUTH2_CLIENT_CREDENTIALS, set auth_config.api_key when this is API_KEY, and omit auth_config when this is NONE.","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external HTTP API or remote MCP server","type":"string"},"connector_protocol":{"description":"Connector protocol. Defaults to HTTP when omitted and cannot be changed after creation.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of what this connector integrates with and its purpose. The agent uses this to understand the connector capabilities, e.g. 'Connects to the Shopify API for managing customer orders, processing returns, and checking inventory availability.'","type":"string"},"name":{"description":"Display name of the connector. Use a name that clearly identifies the external service (e.g. Shopify_Order_Management, Salesforce_CRM). Must be unique among the connectors already created for this entity. Connector names must contain only letters, numbers, and underscores (regex: ^[A-Za-z0-9_]+$). They must not start or end with an underscore or contain consecutive underscores. Spaces, hyphens, dots, and accented characters are not allowed.","type":"string"},"requires_certificate":{"description":"Whether this connector requires an mTLS client certificate. When true, use the upsertCertificate endpoint to provide it.","type":"boolean"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","description","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorAuthConfig":{"description":"Authentication configuration for this connector","properties":{"api_key":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"},"oauth2_client_credentials":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig":{"description":"API key configuration. Provide only when auth_type is API_KEY.","properties":{"body_params":{"description":"API key fields to add as JSON body parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"headers":{"description":"API key fields to add as HTTP headers","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"query_params":{"description":"API key fields to add as query parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam":{"description":"A single API key field","properties":{"field_name":{"description":"Header, query parameter, or body field name","type":"string"},"prefix":{"description":"Optional value prefix, such as Bearer followed by a space","type":"string"},"value":{"description":"Secret value for this API key field","type":"string"}},"required":["field_name","value"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig":{"description":"OAuth 2.0 client credentials configuration. Provide only when auth_type is OAUTH2_CLIENT_CREDENTIALS.","properties":{"client_id":{"description":"OAuth client ID","type":"string"},"client_secret":{"description":"OAuth client secret","type":"string"},"scopes_to_request":{"description":"OAuth scopes to request","items":{"type":"string"},"type":"array","uniqueItems":false},"token_request_content_type":{"description":"Content type for token requests. Supports application/x-www-form-urlencoded and application/json. Defaults to application/x-www-form-urlencoded.","type":"string"},"token_url":{"description":"Token URL used to request OAuth access tokens","type":"string"}},"required":["client_id","client_secret","scopes_to_request","token_url"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig":{"description":"Configuration for injecting user auth tokens into tool requests","properties":{"field_name":{"description":"Field name for the injected token (e.g. X-User-Token)","type":"string"},"location":{"description":"Where to inject the token","enum":["body","headers","path","query"],"type":"string"},"prefix":{"description":"Prefix for the token value (e.g. Bearer )","type":"string"}},"required":["field_name","location","prefix"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorResponse":{"description":"A single connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type for this connector","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external API","type":"string"},"connection_status":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus"},"connector_protocol":{"description":"Protocol used by this connector. Defaults to HTTP when omitted.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of the connector","type":"string"},"id":{"description":"The unique identifier for this connector","type":"string"},"mcp_tool_sync":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync"},"mtls_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig"},"name":{"description":"Display name of the connector","type":"string"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","connection_status","description","id","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus":{"description":"Connection status information","properties":{"error_message":{"description":"Error message if connection failed","type":"string"},"status":{"description":"Current connection status","enum":["PENDING_OAUTH","ACTIVE","EXPIRED","ERROR"],"type":"string"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync":{"description":"MCP tool discovery cache status. Null for HTTP connectors.","properties":{"fingerprint":{"description":"Fingerprint of the cached remote tool set","type":"string"},"last_attempted_at":{"description":"Unix timestamp of the latest refresh attempt","type":"integer"},"last_successful_at":{"description":"Unix timestamp of the latest successful refresh","type":"integer"},"status":{"description":"Current MCP tool refresh status","enum":["ERROR","PENDING","READY"],"type":"string"},"tool_count":{"description":"Number of cached remote MCP tools","type":"integer"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig":{"description":"mTLS certificate metadata and PEM content (private key is never exposed)","properties":{"ca_certificate":{"description":"PEM-encoded CA certificate chain (public, safe to expose)","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate (public, safe to expose)","type":"string"},"expires_at":{"description":"Unix timestamp of certificate expiry","type":"integer"},"fingerprint":{"description":"SHA-256 fingerprint of the certificate","type":"string"},"has_certificate":{"description":"Whether an mTLS certificate is configured","type":"boolean"},"subject":{"description":"Certificate subject DN","type":"string"}},"required":["has_certificate"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}":{"put":{"description":"Update a specific connector by its ID.","operationId":"put-agent-connectors-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorRequest","summary":"requestBody","description":"Updated connector"}}},"description":"Updated connector","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorResponse"}}},"description":"The updated connector"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"Update a connector","tags":["Knowledge - Connectors"]}}}}
```
# Delete a connector
Delete a specific connector by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}":{"delete":{"description":"Delete a specific connector by its ID.","operationId":"delete-agent-connectors-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Connector successfully deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"Delete a connector","tags":["Knowledge - Connectors"]}}}}
```
# List connector error logs
Retrieve error logs for the connector. Returns individual log entries by default, or aggregated failure patterns when summary\_only is true. Optionally includes aggregate statistics. Only third-party errors are included. The time range must not exceed 7 days and logs are available for the last 7 days only.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorLogStatsResponse":{"description":"Log entries or failure patterns, with optional statistics","properties":{"data":{"description":"Array of log entries or failure patterns depending on query mode","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorLogEntry"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorLogStats"}},"required":["data"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorLogEntry":{"description":"A log entry (individual mode) or failure pattern (summary_only mode)","properties":{"error_message":{"description":"Error message from the failed operation","type":"string"},"event_time":{"description":"ISO 8601 UTC timestamp of when the error event occurred (individual log entry mode)","type":"string"},"failure_code_name":{"description":"Human-readable name of the failure code (e.g. TRANSPORT_ERROR)","type":"string"},"last_seen":{"description":"ISO 8601 UTC timestamp of the most recent occurrence (summary_only mode)","type":"string"},"occurrences":{"description":"Number of times this failure pattern occurred (summary_only mode)","type":"integer"},"tool_name":{"description":"The tool that was being used when the error occurred","type":"string"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorLogStats":{"description":"Aggregate statistics for the queried time window, present when include_stats is true","properties":{"avg_latency_s":{"description":"Average execution latency in seconds","type":"number"},"exception_count":{"description":"Number of failed tool executions","type":"integer"},"p95_latency_s":{"description":"95th percentile execution latency in seconds","type":"number"},"p99_latency_s":{"description":"99th percentile execution latency in seconds","type":"number"},"start_count":{"description":"Total number of tool execution starts","type":"integer"},"success_count":{"description":"Number of successful tool executions","type":"integer"},"success_rate":{"description":"Ratio of successful executions to total starts","type":"number"},"time_window_seconds":{"description":"Number of seconds in the statistics time window. Reflects the actual covered window, which may be smaller than the requested range if the most recent logs have not yet been processed.","type":"integer"}},"required":["avg_latency_s","exception_count","p95_latency_s","p99_latency_s","start_count","success_count","success_rate","time_window_seconds"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/logs":{"get":{"description":"Retrieve error logs for the connector. Returns individual log entries by default, or aggregated failure patterns when summary_only is true. Optionally includes aggregate statistics. Only third-party errors are included. The time range must not exceed 7 days and logs are available for the last 7 days only.","operationId":"get-agent-connectors-logs","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}},{"description":"Start of the time range (Unix seconds). Defaults to 24 hours ago. Must be within the last 7 days.","in":"query","name":"start_time","schema":{"type":"integer"}},{"description":"End of the time range (Unix seconds). Defaults to now.","in":"query","name":"end_time","schema":{"type":"integer"}},{"description":"Maximum number of log entries to return (1-1000). Defaults to 100.","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Optional tool ID to filter logs to a specific operation.","in":"query","name":"tool_id","schema":{"type":"string"}},{"description":"When true, include aggregate statistics (success rate, latency percentiles, counts) in the response. The returned time_window_seconds reflects the actual covered window, which may be smaller than the requested range. Defaults to false.","in":"query","name":"include_stats","schema":{"type":"boolean"}},{"description":"When true, return aggregated failure patterns instead of individual log entries. Defaults to false.","in":"query","name":"summary_only","schema":{"type":"boolean"}},{"description":"Number of top failure patterns to return when summary_only is true (1-50). Defaults to 10.","in":"query","name":"top_n","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorLogStatsResponse"}}},"description":"Log entries or failure patterns, with optional statistics"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"List connector error logs","tags":["Knowledge - Connectors"]}}}}
```
# Refresh MCP tools for a connector
Discover the remote MCP server tools and reconcile the cached connector actions. The response reports the resulting refresh status and retains the previous successful tool set if discovery fails. Remote discovery and provisioning failures return HTTP 200 with an ERROR refresh status.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorResponse":{"description":"A single connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type for this connector","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external API","type":"string"},"connection_status":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus"},"connector_protocol":{"description":"Protocol used by this connector. Defaults to HTTP when omitted.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of the connector","type":"string"},"id":{"description":"The unique identifier for this connector","type":"string"},"mcp_tool_sync":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync"},"mtls_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig"},"name":{"description":"Display name of the connector","type":"string"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","connection_status","description","id","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorAuthConfig":{"description":"Authentication configuration for this connector","properties":{"api_key":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"},"oauth2_client_credentials":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig":{"description":"API key configuration. Provide only when auth_type is API_KEY.","properties":{"body_params":{"description":"API key fields to add as JSON body parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"headers":{"description":"API key fields to add as HTTP headers","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"query_params":{"description":"API key fields to add as query parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam":{"description":"A single API key field","properties":{"field_name":{"description":"Header, query parameter, or body field name","type":"string"},"prefix":{"description":"Optional value prefix, such as Bearer followed by a space","type":"string"},"value":{"description":"Secret value for this API key field","type":"string"}},"required":["field_name","value"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig":{"description":"OAuth 2.0 client credentials configuration. Provide only when auth_type is OAUTH2_CLIENT_CREDENTIALS.","properties":{"client_id":{"description":"OAuth client ID","type":"string"},"client_secret":{"description":"OAuth client secret","type":"string"},"scopes_to_request":{"description":"OAuth scopes to request","items":{"type":"string"},"type":"array","uniqueItems":false},"token_request_content_type":{"description":"Content type for token requests. Supports application/x-www-form-urlencoded and application/json. Defaults to application/x-www-form-urlencoded.","type":"string"},"token_url":{"description":"Token URL used to request OAuth access tokens","type":"string"}},"required":["client_id","client_secret","scopes_to_request","token_url"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus":{"description":"Connection status information","properties":{"error_message":{"description":"Error message if connection failed","type":"string"},"status":{"description":"Current connection status","enum":["PENDING_OAUTH","ACTIVE","EXPIRED","ERROR"],"type":"string"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync":{"description":"MCP tool discovery cache status. Null for HTTP connectors.","properties":{"fingerprint":{"description":"Fingerprint of the cached remote tool set","type":"string"},"last_attempted_at":{"description":"Unix timestamp of the latest refresh attempt","type":"integer"},"last_successful_at":{"description":"Unix timestamp of the latest successful refresh","type":"integer"},"status":{"description":"Current MCP tool refresh status","enum":["ERROR","PENDING","READY"],"type":"string"},"tool_count":{"description":"Number of cached remote MCP tools","type":"integer"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig":{"description":"mTLS certificate metadata and PEM content (private key is never exposed)","properties":{"ca_certificate":{"description":"PEM-encoded CA certificate chain (public, safe to expose)","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate (public, safe to expose)","type":"string"},"expires_at":{"description":"Unix timestamp of certificate expiry","type":"integer"},"fingerprint":{"description":"SHA-256 fingerprint of the certificate","type":"string"},"has_certificate":{"description":"Whether an mTLS certificate is configured","type":"boolean"},"subject":{"description":"Certificate subject DN","type":"string"}},"required":["has_certificate"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig":{"description":"Configuration for injecting user auth tokens into tool requests","properties":{"field_name":{"description":"Field name for the injected token (e.g. X-User-Token)","type":"string"},"location":{"description":"Where to inject the token","enum":["body","headers","path","query"],"type":"string"},"prefix":{"description":"Prefix for the token value (e.g. Bearer )","type":"string"}},"required":["field_name","location","prefix"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/refreshMCPTools":{"post":{"description":"Discover the remote MCP server tools and reconcile the cached connector actions. The response reports the resulting refresh status and retains the previous successful tool set if discovery fails. Remote discovery and provisioning failures return HTTP 200 with an ERROR refresh status.","operationId":"post-agent-connectors-refresh-mcp-tools","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the MCP connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorResponse"}}},"description":"The connector with updated MCP tool sync metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"Refresh MCP tools for a connector","tags":["Knowledge - Connectors"]}}}}
```
# Upsert API key credentials for a connector
Set or rotate the API key credentials for this connector. If credentials already exist, they are replaced and the connection is re-established. The credential payload is required; this endpoint will not delete credentials. At least one of headers, query\_params, or body\_params must contain a populated entry; the request fails with HTTP 400 if api\_key\_config is null or missing. To remove an API key layer, delete the connector or change its auth type via the update endpoint instead.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorUpsertApiKeyRequest":{"description":"Set or rotate the API key credentials for a connector","properties":{"api_key_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"}},"required":["api_key_config"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig":{"description":"API key configuration. Provide only when auth_type is API_KEY.","properties":{"body_params":{"description":"API key fields to add as JSON body parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"headers":{"description":"API key fields to add as HTTP headers","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"query_params":{"description":"API key fields to add as query parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam":{"description":"A single API key field","properties":{"field_name":{"description":"Header, query parameter, or body field name","type":"string"},"prefix":{"description":"Optional value prefix, such as Bearer followed by a space","type":"string"},"value":{"description":"Secret value for this API key field","type":"string"}},"required":["field_name","value"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorResponse":{"description":"A single connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type for this connector","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external API","type":"string"},"connection_status":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus"},"connector_protocol":{"description":"Protocol used by this connector. Defaults to HTTP when omitted.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of the connector","type":"string"},"id":{"description":"The unique identifier for this connector","type":"string"},"mcp_tool_sync":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync"},"mtls_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig"},"name":{"description":"Display name of the connector","type":"string"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","connection_status","description","id","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorAuthConfig":{"description":"Authentication configuration for this connector","properties":{"api_key":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"},"oauth2_client_credentials":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig":{"description":"OAuth 2.0 client credentials configuration. Provide only when auth_type is OAUTH2_CLIENT_CREDENTIALS.","properties":{"client_id":{"description":"OAuth client ID","type":"string"},"client_secret":{"description":"OAuth client secret","type":"string"},"scopes_to_request":{"description":"OAuth scopes to request","items":{"type":"string"},"type":"array","uniqueItems":false},"token_request_content_type":{"description":"Content type for token requests. Supports application/x-www-form-urlencoded and application/json. Defaults to application/x-www-form-urlencoded.","type":"string"},"token_url":{"description":"Token URL used to request OAuth access tokens","type":"string"}},"required":["client_id","client_secret","scopes_to_request","token_url"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus":{"description":"Connection status information","properties":{"error_message":{"description":"Error message if connection failed","type":"string"},"status":{"description":"Current connection status","enum":["PENDING_OAUTH","ACTIVE","EXPIRED","ERROR"],"type":"string"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync":{"description":"MCP tool discovery cache status. Null for HTTP connectors.","properties":{"fingerprint":{"description":"Fingerprint of the cached remote tool set","type":"string"},"last_attempted_at":{"description":"Unix timestamp of the latest refresh attempt","type":"integer"},"last_successful_at":{"description":"Unix timestamp of the latest successful refresh","type":"integer"},"status":{"description":"Current MCP tool refresh status","enum":["ERROR","PENDING","READY"],"type":"string"},"tool_count":{"description":"Number of cached remote MCP tools","type":"integer"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig":{"description":"mTLS certificate metadata and PEM content (private key is never exposed)","properties":{"ca_certificate":{"description":"PEM-encoded CA certificate chain (public, safe to expose)","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate (public, safe to expose)","type":"string"},"expires_at":{"description":"Unix timestamp of certificate expiry","type":"integer"},"fingerprint":{"description":"SHA-256 fingerprint of the certificate","type":"string"},"has_certificate":{"description":"Whether an mTLS certificate is configured","type":"boolean"},"subject":{"description":"Certificate subject DN","type":"string"}},"required":["has_certificate"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig":{"description":"Configuration for injecting user auth tokens into tool requests","properties":{"field_name":{"description":"Field name for the injected token (e.g. X-User-Token)","type":"string"},"location":{"description":"Where to inject the token","enum":["body","headers","path","query"],"type":"string"},"prefix":{"description":"Prefix for the token value (e.g. Bearer )","type":"string"}},"required":["field_name","location","prefix"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/upsertApiKey":{"post":{"description":"Set or rotate the API key credentials for this connector. If credentials already exist, they are replaced and the connection is re-established. The credential payload is required; this endpoint will not delete credentials. At least one of headers, query_params, or body_params must contain a populated entry; the request fails with HTTP 400 if api_key_config is null or missing. To remove an API key layer, delete the connector or change its auth type via the update endpoint instead.","operationId":"post-agent-connectors-upsert-apikey","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUpsertApiKeyRequest","summary":"requestBody","description":"API key credentials to upsert"}}},"description":"API key credentials to upsert","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorResponse"}}},"description":"The updated connector with API key metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"Upsert API key credentials for a connector","tags":["Knowledge - Connectors"]}}}}
```
# Upsert mTLS certificate for a connector
Upload or rotate the mTLS client certificate for this connector. If a certificate already exists, it is replaced and the connection is re-established.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorCertificateRequest":{"description":"Upload or rotate the mTLS client certificate for a connector","properties":{"ca_certificate":{"description":"Optional PEM-encoded CA certificate for the client-side mTLS trust chain.","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate for mTLS. Must begin with -----BEGIN CERTIFICATE-----.","type":"string"},"client_key":{"description":"PEM-encoded private key for mTLS (PKCS8, RSA, or EC).","type":"string"}},"required":["client_certificate","client_key"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorResponse":{"description":"A single connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type for this connector","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external API","type":"string"},"connection_status":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus"},"connector_protocol":{"description":"Protocol used by this connector. Defaults to HTTP when omitted.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of the connector","type":"string"},"id":{"description":"The unique identifier for this connector","type":"string"},"mcp_tool_sync":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync"},"mtls_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig"},"name":{"description":"Display name of the connector","type":"string"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","connection_status","description","id","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorAuthConfig":{"description":"Authentication configuration for this connector","properties":{"api_key":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"},"oauth2_client_credentials":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig":{"description":"API key configuration. Provide only when auth_type is API_KEY.","properties":{"body_params":{"description":"API key fields to add as JSON body parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"headers":{"description":"API key fields to add as HTTP headers","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"query_params":{"description":"API key fields to add as query parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam":{"description":"A single API key field","properties":{"field_name":{"description":"Header, query parameter, or body field name","type":"string"},"prefix":{"description":"Optional value prefix, such as Bearer followed by a space","type":"string"},"value":{"description":"Secret value for this API key field","type":"string"}},"required":["field_name","value"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig":{"description":"OAuth 2.0 client credentials configuration. Provide only when auth_type is OAUTH2_CLIENT_CREDENTIALS.","properties":{"client_id":{"description":"OAuth client ID","type":"string"},"client_secret":{"description":"OAuth client secret","type":"string"},"scopes_to_request":{"description":"OAuth scopes to request","items":{"type":"string"},"type":"array","uniqueItems":false},"token_request_content_type":{"description":"Content type for token requests. Supports application/x-www-form-urlencoded and application/json. Defaults to application/x-www-form-urlencoded.","type":"string"},"token_url":{"description":"Token URL used to request OAuth access tokens","type":"string"}},"required":["client_id","client_secret","scopes_to_request","token_url"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus":{"description":"Connection status information","properties":{"error_message":{"description":"Error message if connection failed","type":"string"},"status":{"description":"Current connection status","enum":["PENDING_OAUTH","ACTIVE","EXPIRED","ERROR"],"type":"string"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync":{"description":"MCP tool discovery cache status. Null for HTTP connectors.","properties":{"fingerprint":{"description":"Fingerprint of the cached remote tool set","type":"string"},"last_attempted_at":{"description":"Unix timestamp of the latest refresh attempt","type":"integer"},"last_successful_at":{"description":"Unix timestamp of the latest successful refresh","type":"integer"},"status":{"description":"Current MCP tool refresh status","enum":["ERROR","PENDING","READY"],"type":"string"},"tool_count":{"description":"Number of cached remote MCP tools","type":"integer"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig":{"description":"mTLS certificate metadata and PEM content (private key is never exposed)","properties":{"ca_certificate":{"description":"PEM-encoded CA certificate chain (public, safe to expose)","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate (public, safe to expose)","type":"string"},"expires_at":{"description":"Unix timestamp of certificate expiry","type":"integer"},"fingerprint":{"description":"SHA-256 fingerprint of the certificate","type":"string"},"has_certificate":{"description":"Whether an mTLS certificate is configured","type":"boolean"},"subject":{"description":"Certificate subject DN","type":"string"}},"required":["has_certificate"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig":{"description":"Configuration for injecting user auth tokens into tool requests","properties":{"field_name":{"description":"Field name for the injected token (e.g. X-User-Token)","type":"string"},"location":{"description":"Where to inject the token","enum":["body","headers","path","query"],"type":"string"},"prefix":{"description":"Prefix for the token value (e.g. Bearer )","type":"string"}},"required":["field_name","location","prefix"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/upsertCertificate":{"post":{"description":"Upload or rotate the mTLS client certificate for this connector. If a certificate already exists, it is replaced and the connection is re-established.","operationId":"post-agent-connectors-upsert-certificate","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorCertificateRequest","summary":"requestBody","description":"mTLS certificate to upsert"}}},"description":"mTLS certificate to upsert","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorResponse"}}},"description":"The updated connector with mTLS certificate metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"Upsert mTLS certificate for a connector","tags":["Knowledge - Connectors"]}}}}
```
# Upsert OAuth 2.0 credentials for a connector
Set or rotate the OAuth 2.0 client credentials for this connector. If credentials already exist, they are replaced and the connection is re-established. The credential payload is required; this endpoint will not delete credentials. The request fails with HTTP 400 if oauth\_config is null or missing. To remove an OAuth layer, delete the connector or change its auth type via the update endpoint instead.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connectors","description":"Endpoints for managing the agent's external API connectors"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connectors.BizAIOmniChannelConnectorUpsertOAuthRequest":{"description":"Set or rotate the OAuth 2.0 client credentials for a connector","properties":{"oauth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"required":["oauth_config"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig":{"description":"OAuth 2.0 client credentials configuration. Provide only when auth_type is OAUTH2_CLIENT_CREDENTIALS.","properties":{"client_id":{"description":"OAuth client ID","type":"string"},"client_secret":{"description":"OAuth client secret","type":"string"},"scopes_to_request":{"description":"OAuth scopes to request","items":{"type":"string"},"type":"array","uniqueItems":false},"token_request_content_type":{"description":"Content type for token requests. Supports application/x-www-form-urlencoded and application/json. Defaults to application/x-www-form-urlencoded.","type":"string"},"token_url":{"description":"Token URL used to request OAuth access tokens","type":"string"}},"required":["client_id","client_secret","scopes_to_request","token_url"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorResponse":{"description":"A single connector","properties":{"auth_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorAuthConfig"},"auth_type":{"description":"Authentication type for this connector","enum":["OAUTH2","OAUTH2_CLIENT_CREDENTIALS","API_KEY","BASIC","CUSTOM","NONE"],"type":"string"},"base_url":{"description":"Base URL of the external API","type":"string"},"connection_status":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus"},"connector_protocol":{"description":"Protocol used by this connector. Defaults to HTTP when omitted.","enum":["HTTP","MCP"],"type":"string"},"description":{"description":"Description of the connector","type":"string"},"id":{"description":"The unique identifier for this connector","type":"string"},"mcp_tool_sync":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync"},"mtls_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig"},"name":{"description":"Display name of the connector","type":"string"},"user_auth_injection_config":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig"}},"required":["auth_type","base_url","connection_status","description","id","name"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorAuthConfig":{"description":"Authentication configuration for this connector","properties":{"api_key":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig"},"oauth2_client_credentials":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorOAuth2ClientCredentialsAuthConfig"}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyAuthConfig":{"description":"API key configuration. Provide only when auth_type is API_KEY.","properties":{"body_params":{"description":"API key fields to add as JSON body parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"headers":{"description":"API key fields to add as HTTP headers","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false},"query_params":{"description":"API key fields to add as query parameters","items":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam"},"type":"array","uniqueItems":false}},"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorApiKeyParam":{"description":"A single API key field","properties":{"field_name":{"description":"Header, query parameter, or body field name","type":"string"},"prefix":{"description":"Optional value prefix, such as Bearer followed by a space","type":"string"},"value":{"description":"Secret value for this API key field","type":"string"}},"required":["field_name","value"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorConnectionStatus":{"description":"Connection status information","properties":{"error_message":{"description":"Error message if connection failed","type":"string"},"status":{"description":"Current connection status","enum":["PENDING_OAUTH","ACTIVE","EXPIRED","ERROR"],"type":"string"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMcpToolSync":{"description":"MCP tool discovery cache status. Null for HTTP connectors.","properties":{"fingerprint":{"description":"Fingerprint of the cached remote tool set","type":"string"},"last_attempted_at":{"description":"Unix timestamp of the latest refresh attempt","type":"integer"},"last_successful_at":{"description":"Unix timestamp of the latest successful refresh","type":"integer"},"status":{"description":"Current MCP tool refresh status","enum":["ERROR","PENDING","READY"],"type":"string"},"tool_count":{"description":"Number of cached remote MCP tools","type":"integer"}},"required":["status"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorMtlsConfig":{"description":"mTLS certificate metadata and PEM content (private key is never exposed)","properties":{"ca_certificate":{"description":"PEM-encoded CA certificate chain (public, safe to expose)","type":"string"},"client_certificate":{"description":"PEM-encoded client certificate (public, safe to expose)","type":"string"},"expires_at":{"description":"Unix timestamp of certificate expiry","type":"integer"},"fingerprint":{"description":"SHA-256 fingerprint of the certificate","type":"string"},"has_certificate":{"description":"Whether an mTLS certificate is configured","type":"boolean"},"subject":{"description":"Certificate subject DN","type":"string"}},"required":["has_certificate"],"type":"object"},"knowledge_connectors.BizAIOmniChannelConnectorUserAuthInjectionConfig":{"description":"Configuration for injecting user auth tokens into tool requests","properties":{"field_name":{"description":"Field name for the injected token (e.g. X-User-Token)","type":"string"},"location":{"description":"Where to inject the token","enum":["body","headers","path","query"],"type":"string"},"prefix":{"description":"Prefix for the token value (e.g. Bearer )","type":"string"}},"required":["field_name","location","prefix"],"type":"object"},"knowledge_connectors.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/upsertOAuth":{"post":{"description":"Set or rotate the OAuth 2.0 client credentials for this connector. If credentials already exist, they are replaced and the connection is re-established. The credential payload is required; this endpoint will not delete credentials. The request fails with HTTP 400 if oauth_config is null or missing. To remove an OAuth layer, delete the connector or change its auth type via the update endpoint instead.","operationId":"post-agent-connectors-upsert-oauth","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorUpsertOAuthRequest","summary":"requestBody","description":"OAuth 2.0 credentials to upsert"}}},"description":"OAuth 2.0 credentials to upsert","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.BizAIOmniChannelConnectorResponse"}}},"description":"The updated connector with OAuth credential metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connectors.StandardError"}}},"description":"Server error"}},"summary":"Upsert OAuth 2.0 credentials for a connector","tags":["Knowledge - Connectors"]}}}}
```
# Knowledge Connector Tools
Endpoints for managing tools on an agent connector
# List connector tools
Retrieve a list of all tools for the specified connector.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connector Tools","description":"Endpoints for managing tools on an agent connector"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connector_tools.BizAIOmniChannelConnectorToolResponse":{"description":"A single connector tool","properties":{"description":{"description":"Human-readable tool description","type":"string"},"id":{"description":"Tool ID returned by the Stefi API","type":"string"},"name":{"description":"Stable tool/action key, visible to the agent","type":"string"},"request_definition":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition"},"user_auth_action_config":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthActionConfig"},"user_auth_required":{"description":"Whether Meta Business Agent injects stored user auth into the outbound request at runtime","type":"boolean"}},"required":["description","id","name","request_definition","user_auth_required"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition":{"description":"Roundtripped outbound HTTP request definition","properties":{"body":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestBodyDefinition"},"headers":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Header schema; property names are the canonical outbound header names","type":"object"},"method":{"description":"HTTP method for the outbound request","enum":["GET","POST","PUT","DELETE","PATCH"],"type":"string"},"path":{"description":"Outbound request path template, including {placeholder} segments for path parameters","type":"string"},"path_parameters":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Path-parameter schema; property names must match the placeholder names used in path","type":"object"},"query_parameters":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Query-parameter schema; property names are the canonical outbound query parameter names","type":"object"}},"required":["method","path"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestBodyDefinition":{"description":"Request body definition; omit or set to null when the request has no body","properties":{"content_type":{"description":"Request body content type; currently only supports application/json","enum":["application/json"],"type":"string"},"params":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolBodyNode"},"description":"Top-level JSON body fields; keys are canonical outbound field names","type":"object"},"required":{"description":"Required top-level body fields. Entries must be keys present in params.","items":{"type":"string"},"type":"array","uniqueItems":false}},"required":["content_type","params"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolBodyNode":{"description":"Schema for a request body field or container","properties":{"binding":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding"},"description":{"description":"Human-readable documentation for the field or container","type":"string"},"items":{"description":"BodyNode element schema for array nodes, as a string representation of the BodyNode type. Only for \"array\" nodes.","type":"string"},"properties":{"additionalProperties":{"type":"string"},"description":"Child fields for object nodes; keys are canonical field names, value is a string representation of the BodyNode type. Only for \"object\" nodes.","type":"object"},"required":{"description":"Required properties of this object. Only for \"object\" type nodes.","items":{"type":"string"},"type":"array","uniqueItems":false},"type":{"description":"Node type. Use \"object\" with explicit properties for structured data rather than \"string\".","enum":["object","array","string","integer","number","boolean"],"type":"string"}},"required":["type"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding":{"description":"Meta Business Agent-owned binding for this node; omitted means agent/runtime input. Cannot be provided for an \"object\" or \"array\" type node.","properties":{"kind":{"description":"Source mode for a Meta Business Agent-owned field","enum":["default","macro"],"type":"string"},"macro":{"description":"Registered Meta Business Agent macro ID, required when kind = \"macro\"","enum":["WHATSAPP_PHONE_NUMBER","WHATSAPP_IDENTITY_HASH","WHATSAPP_CURRENT_STATUS_ID"],"type":"string"},"value":{"description":"Typed literal value, required when kind = \"default\". Provided as a string; the underlying value must match the node type.","type":"string"}},"required":["kind"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode":{"description":"Schema for a single path, query, or header parameter","properties":{"binding":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding"},"description":{"description":"Human-readable documentation for the parameter. The agent uses it to understand what value to pass.","type":"string"},"required":{"description":"Whether the field is required. Ignored for path params, which are always required.","type":"boolean"},"type":{"description":"Node type","enum":["string","integer","number","boolean"],"type":"string"}},"required":["type"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthActionConfig":{"description":"Response extraction config for login/refresh user-auth actions","properties":{"expires_at_path":{"description":"Dot-path used to extract token expiry from a login/refresh tool response","type":"string"},"expires_at_type":{"description":"How to interpret the value found at expires_at_path","enum":["absolute","relative_seconds"],"type":"string"},"refresh_token_path":{"description":"Dot-path used to extract the refresh token from a login/refresh tool response","type":"string"},"user_action_tool_type":{"description":"Type of user auth action: auth performs initial authorization, refresh uses an existing refresh token","enum":["auth","refresh"],"type":"string"},"user_auth_token_path":{"description":"Dot-path used to extract the access token from a login/refresh tool response","type":"string"}},"required":["user_action_tool_type","user_auth_token_path"],"type":"object"},"knowledge_connector_tools.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/tools":{"get":{"description":"Retrieve a list of all tools for the specified connector.","operationId":"get-agent-connector-tools","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the parent connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolResponse"},"type":"array"}}},"description":"A list of all tools"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Server error"}},"summary":"List connector tools","tags":["Knowledge - Connector Tools"]}}}}
```
# Create a connector tool
Create a new tool for the specified connector.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connector Tools","description":"Endpoints for managing tools on an agent connector"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequest":{"description":"Create or update a connector tool","properties":{"description":{"description":"Human-readable description of what this tool does and when to use it. The agent relies on this to decide when to invoke the tool.","type":"string"},"name":{"description":"Stable tool/action key, visible to the agent. Use a clear, descriptive name (e.g. check_order_status).","type":"string"},"request_definition":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition"},"user_auth_action_config":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthToolConfig"},"user_auth_required":{"description":"If true, Meta Business Agent injects stored user auth into the outbound request at runtime","type":"boolean"}},"required":["description","name","request_definition","user_auth_required"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition":{"description":"Roundtripped outbound HTTP request definition","properties":{"body":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestBodyDefinition"},"headers":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Header schema; property names are the canonical outbound header names","type":"object"},"method":{"description":"HTTP method for the outbound request","enum":["GET","POST","PUT","DELETE","PATCH"],"type":"string"},"path":{"description":"Outbound request path template, including {placeholder} segments for path parameters","type":"string"},"path_parameters":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Path-parameter schema; property names must match the placeholder names used in path","type":"object"},"query_parameters":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Query-parameter schema; property names are the canonical outbound query parameter names","type":"object"}},"required":["method","path"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestBodyDefinition":{"description":"Request body definition; omit or set to null when the request has no body","properties":{"content_type":{"description":"Request body content type; currently only supports application/json","enum":["application/json"],"type":"string"},"params":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolBodyNode"},"description":"Top-level JSON body fields; keys are canonical outbound field names","type":"object"},"required":{"description":"Required top-level body fields. Entries must be keys present in params.","items":{"type":"string"},"type":"array","uniqueItems":false}},"required":["content_type","params"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolBodyNode":{"description":"Schema for a request body field or container","properties":{"binding":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding"},"description":{"description":"Human-readable documentation for the field or container","type":"string"},"items":{"description":"BodyNode element schema for array nodes, as a string representation of the BodyNode type. Only for \"array\" nodes.","type":"string"},"properties":{"additionalProperties":{"type":"string"},"description":"Child fields for object nodes; keys are canonical field names, value is a string representation of the BodyNode type. Only for \"object\" nodes.","type":"object"},"required":{"description":"Required properties of this object. Only for \"object\" type nodes.","items":{"type":"string"},"type":"array","uniqueItems":false},"type":{"description":"Node type. Use \"object\" with explicit properties for structured data rather than \"string\".","enum":["object","array","string","integer","number","boolean"],"type":"string"}},"required":["type"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding":{"description":"Meta Business Agent-owned binding for this node; omitted means agent/runtime input. Cannot be provided for an \"object\" or \"array\" type node.","properties":{"kind":{"description":"Source mode for a Meta Business Agent-owned field","enum":["default","macro"],"type":"string"},"macro":{"description":"Registered Meta Business Agent macro ID, required when kind = \"macro\"","enum":["WHATSAPP_PHONE_NUMBER","WHATSAPP_IDENTITY_HASH","WHATSAPP_CURRENT_STATUS_ID"],"type":"string"},"value":{"description":"Typed literal value, required when kind = \"default\". Provided as a string; the underlying value must match the node type.","type":"string"}},"required":["kind"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode":{"description":"Schema for a single path, query, or header parameter","properties":{"binding":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding"},"description":{"description":"Human-readable documentation for the parameter. The agent uses it to understand what value to pass.","type":"string"},"required":{"description":"Whether the field is required. Ignored for path params, which are always required.","type":"boolean"},"type":{"description":"Node type","enum":["string","integer","number","boolean"],"type":"string"}},"required":["type"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthToolConfig":{"description":"Response extraction config for login/refresh user-auth actions","properties":{"expires_at_path":{"description":"Dot-path used to extract token expiry from a login/refresh tool response","type":"string"},"expires_at_type":{"description":"How to interpret the value found at expires_at_path","enum":["absolute","relative_seconds"],"type":"string"},"refresh_token_path":{"description":"Dot-path used to extract the refresh token from a login/refresh tool response","type":"string"},"user_action_tool_type":{"description":"Type of user auth action: auth performs initial authorization, refresh uses an existing refresh token","enum":["auth","refresh"],"type":"string"},"user_auth_token_path":{"description":"Dot-path used to extract the access token from a login/refresh tool response","type":"string"}},"required":["user_action_tool_type","user_auth_token_path"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolResponse":{"description":"A single connector tool","properties":{"description":{"description":"Human-readable tool description","type":"string"},"id":{"description":"Tool ID returned by the Stefi API","type":"string"},"name":{"description":"Stable tool/action key, visible to the agent","type":"string"},"request_definition":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition"},"user_auth_action_config":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthActionConfig"},"user_auth_required":{"description":"Whether Meta Business Agent injects stored user auth into the outbound request at runtime","type":"boolean"}},"required":["description","id","name","request_definition","user_auth_required"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthActionConfig":{"description":"Response extraction config for login/refresh user-auth actions","properties":{"expires_at_path":{"description":"Dot-path used to extract token expiry from a login/refresh tool response","type":"string"},"expires_at_type":{"description":"How to interpret the value found at expires_at_path","enum":["absolute","relative_seconds"],"type":"string"},"refresh_token_path":{"description":"Dot-path used to extract the refresh token from a login/refresh tool response","type":"string"},"user_action_tool_type":{"description":"Type of user auth action: auth performs initial authorization, refresh uses an existing refresh token","enum":["auth","refresh"],"type":"string"},"user_auth_token_path":{"description":"Dot-path used to extract the access token from a login/refresh tool response","type":"string"}},"required":["user_action_tool_type","user_auth_token_path"],"type":"object"},"knowledge_connector_tools.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/tools":{"post":{"description":"Create a new tool for the specified connector.","operationId":"post-agent-connector-tools","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the parent connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequest","summary":"requestBody","description":"Tool to create"}}},"description":"Tool to create","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolResponse"}}},"description":"The newly created tool"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Server error"}},"summary":"Create a connector tool","tags":["Knowledge - Connector Tools"]}}}}
```
# Get a connector tool
Retrieve a specific tool by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connector Tools","description":"Endpoints for managing tools on an agent connector"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connector_tools.BizAIOmniChannelConnectorToolResponse":{"description":"A single connector tool","properties":{"description":{"description":"Human-readable tool description","type":"string"},"id":{"description":"Tool ID returned by the Stefi API","type":"string"},"name":{"description":"Stable tool/action key, visible to the agent","type":"string"},"request_definition":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition"},"user_auth_action_config":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthActionConfig"},"user_auth_required":{"description":"Whether Meta Business Agent injects stored user auth into the outbound request at runtime","type":"boolean"}},"required":["description","id","name","request_definition","user_auth_required"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition":{"description":"Roundtripped outbound HTTP request definition","properties":{"body":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestBodyDefinition"},"headers":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Header schema; property names are the canonical outbound header names","type":"object"},"method":{"description":"HTTP method for the outbound request","enum":["GET","POST","PUT","DELETE","PATCH"],"type":"string"},"path":{"description":"Outbound request path template, including {placeholder} segments for path parameters","type":"string"},"path_parameters":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Path-parameter schema; property names must match the placeholder names used in path","type":"object"},"query_parameters":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Query-parameter schema; property names are the canonical outbound query parameter names","type":"object"}},"required":["method","path"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestBodyDefinition":{"description":"Request body definition; omit or set to null when the request has no body","properties":{"content_type":{"description":"Request body content type; currently only supports application/json","enum":["application/json"],"type":"string"},"params":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolBodyNode"},"description":"Top-level JSON body fields; keys are canonical outbound field names","type":"object"},"required":{"description":"Required top-level body fields. Entries must be keys present in params.","items":{"type":"string"},"type":"array","uniqueItems":false}},"required":["content_type","params"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolBodyNode":{"description":"Schema for a request body field or container","properties":{"binding":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding"},"description":{"description":"Human-readable documentation for the field or container","type":"string"},"items":{"description":"BodyNode element schema for array nodes, as a string representation of the BodyNode type. Only for \"array\" nodes.","type":"string"},"properties":{"additionalProperties":{"type":"string"},"description":"Child fields for object nodes; keys are canonical field names, value is a string representation of the BodyNode type. Only for \"object\" nodes.","type":"object"},"required":{"description":"Required properties of this object. Only for \"object\" type nodes.","items":{"type":"string"},"type":"array","uniqueItems":false},"type":{"description":"Node type. Use \"object\" with explicit properties for structured data rather than \"string\".","enum":["object","array","string","integer","number","boolean"],"type":"string"}},"required":["type"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding":{"description":"Meta Business Agent-owned binding for this node; omitted means agent/runtime input. Cannot be provided for an \"object\" or \"array\" type node.","properties":{"kind":{"description":"Source mode for a Meta Business Agent-owned field","enum":["default","macro"],"type":"string"},"macro":{"description":"Registered Meta Business Agent macro ID, required when kind = \"macro\"","enum":["WHATSAPP_PHONE_NUMBER","WHATSAPP_IDENTITY_HASH","WHATSAPP_CURRENT_STATUS_ID"],"type":"string"},"value":{"description":"Typed literal value, required when kind = \"default\". Provided as a string; the underlying value must match the node type.","type":"string"}},"required":["kind"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode":{"description":"Schema for a single path, query, or header parameter","properties":{"binding":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding"},"description":{"description":"Human-readable documentation for the parameter. The agent uses it to understand what value to pass.","type":"string"},"required":{"description":"Whether the field is required. Ignored for path params, which are always required.","type":"boolean"},"type":{"description":"Node type","enum":["string","integer","number","boolean"],"type":"string"}},"required":["type"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthActionConfig":{"description":"Response extraction config for login/refresh user-auth actions","properties":{"expires_at_path":{"description":"Dot-path used to extract token expiry from a login/refresh tool response","type":"string"},"expires_at_type":{"description":"How to interpret the value found at expires_at_path","enum":["absolute","relative_seconds"],"type":"string"},"refresh_token_path":{"description":"Dot-path used to extract the refresh token from a login/refresh tool response","type":"string"},"user_action_tool_type":{"description":"Type of user auth action: auth performs initial authorization, refresh uses an existing refresh token","enum":["auth","refresh"],"type":"string"},"user_auth_token_path":{"description":"Dot-path used to extract the access token from a login/refresh tool response","type":"string"}},"required":["user_action_tool_type","user_auth_token_path"],"type":"object"},"knowledge_connector_tools.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/tools/{tool_id}":{"get":{"description":"Retrieve a specific tool by its ID.","operationId":"get-agent-connector-tools-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the parent connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of the tool","in":"path","name":"tool_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolResponse"}}},"description":"The requested tool"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Server error"}},"summary":"Get a connector tool","tags":["Knowledge - Connector Tools"]}}}}
```
# Update a connector tool
Update a specific tool by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connector Tools","description":"Endpoints for managing tools on an agent connector"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequest":{"description":"Create or update a connector tool","properties":{"description":{"description":"Human-readable description of what this tool does and when to use it. The agent relies on this to decide when to invoke the tool.","type":"string"},"name":{"description":"Stable tool/action key, visible to the agent. Use a clear, descriptive name (e.g. check_order_status).","type":"string"},"request_definition":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition"},"user_auth_action_config":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthToolConfig"},"user_auth_required":{"description":"If true, Meta Business Agent injects stored user auth into the outbound request at runtime","type":"boolean"}},"required":["description","name","request_definition","user_auth_required"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition":{"description":"Roundtripped outbound HTTP request definition","properties":{"body":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestBodyDefinition"},"headers":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Header schema; property names are the canonical outbound header names","type":"object"},"method":{"description":"HTTP method for the outbound request","enum":["GET","POST","PUT","DELETE","PATCH"],"type":"string"},"path":{"description":"Outbound request path template, including {placeholder} segments for path parameters","type":"string"},"path_parameters":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Path-parameter schema; property names must match the placeholder names used in path","type":"object"},"query_parameters":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode"},"description":"Query-parameter schema; property names are the canonical outbound query parameter names","type":"object"}},"required":["method","path"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestBodyDefinition":{"description":"Request body definition; omit or set to null when the request has no body","properties":{"content_type":{"description":"Request body content type; currently only supports application/json","enum":["application/json"],"type":"string"},"params":{"additionalProperties":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolBodyNode"},"description":"Top-level JSON body fields; keys are canonical outbound field names","type":"object"},"required":{"description":"Required top-level body fields. Entries must be keys present in params.","items":{"type":"string"},"type":"array","uniqueItems":false}},"required":["content_type","params"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolBodyNode":{"description":"Schema for a request body field or container","properties":{"binding":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding"},"description":{"description":"Human-readable documentation for the field or container","type":"string"},"items":{"description":"BodyNode element schema for array nodes, as a string representation of the BodyNode type. Only for \"array\" nodes.","type":"string"},"properties":{"additionalProperties":{"type":"string"},"description":"Child fields for object nodes; keys are canonical field names, value is a string representation of the BodyNode type. Only for \"object\" nodes.","type":"object"},"required":{"description":"Required properties of this object. Only for \"object\" type nodes.","items":{"type":"string"},"type":"array","uniqueItems":false},"type":{"description":"Node type. Use \"object\" with explicit properties for structured data rather than \"string\".","enum":["object","array","string","integer","number","boolean"],"type":"string"}},"required":["type"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding":{"description":"Meta Business Agent-owned binding for this node; omitted means agent/runtime input. Cannot be provided for an \"object\" or \"array\" type node.","properties":{"kind":{"description":"Source mode for a Meta Business Agent-owned field","enum":["default","macro"],"type":"string"},"macro":{"description":"Registered Meta Business Agent macro ID, required when kind = \"macro\"","enum":["WHATSAPP_PHONE_NUMBER","WHATSAPP_IDENTITY_HASH","WHATSAPP_CURRENT_STATUS_ID"],"type":"string"},"value":{"description":"Typed literal value, required when kind = \"default\". Provided as a string; the underlying value must match the node type.","type":"string"}},"required":["kind"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterNode":{"description":"Schema for a single path, query, or header parameter","properties":{"binding":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolParameterBinding"},"description":{"description":"Human-readable documentation for the parameter. The agent uses it to understand what value to pass.","type":"string"},"required":{"description":"Whether the field is required. Ignored for path params, which are always required.","type":"boolean"},"type":{"description":"Node type","enum":["string","integer","number","boolean"],"type":"string"}},"required":["type"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthToolConfig":{"description":"Response extraction config for login/refresh user-auth actions","properties":{"expires_at_path":{"description":"Dot-path used to extract token expiry from a login/refresh tool response","type":"string"},"expires_at_type":{"description":"How to interpret the value found at expires_at_path","enum":["absolute","relative_seconds"],"type":"string"},"refresh_token_path":{"description":"Dot-path used to extract the refresh token from a login/refresh tool response","type":"string"},"user_action_tool_type":{"description":"Type of user auth action: auth performs initial authorization, refresh uses an existing refresh token","enum":["auth","refresh"],"type":"string"},"user_auth_token_path":{"description":"Dot-path used to extract the access token from a login/refresh tool response","type":"string"}},"required":["user_action_tool_type","user_auth_token_path"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolResponse":{"description":"A single connector tool","properties":{"description":{"description":"Human-readable tool description","type":"string"},"id":{"description":"Tool ID returned by the Stefi API","type":"string"},"name":{"description":"Stable tool/action key, visible to the agent","type":"string"},"request_definition":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequestDefinition"},"user_auth_action_config":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthActionConfig"},"user_auth_required":{"description":"Whether Meta Business Agent injects stored user auth into the outbound request at runtime","type":"boolean"}},"required":["description","id","name","request_definition","user_auth_required"],"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolUserAuthActionConfig":{"description":"Response extraction config for login/refresh user-auth actions","properties":{"expires_at_path":{"description":"Dot-path used to extract token expiry from a login/refresh tool response","type":"string"},"expires_at_type":{"description":"How to interpret the value found at expires_at_path","enum":["absolute","relative_seconds"],"type":"string"},"refresh_token_path":{"description":"Dot-path used to extract the refresh token from a login/refresh tool response","type":"string"},"user_action_tool_type":{"description":"Type of user auth action: auth performs initial authorization, refresh uses an existing refresh token","enum":["auth","refresh"],"type":"string"},"user_auth_token_path":{"description":"Dot-path used to extract the access token from a login/refresh tool response","type":"string"}},"required":["user_action_tool_type","user_auth_token_path"],"type":"object"},"knowledge_connector_tools.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/tools/{tool_id}":{"put":{"description":"Update a specific tool by its ID.","operationId":"put-agent-connector-tools-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the parent connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of the tool","in":"path","name":"tool_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRequest","summary":"requestBody","description":"Updated tool"}}},"description":"Updated tool","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolResponse"}}},"description":"The updated tool"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Server error"}},"summary":"Update a connector tool","tags":["Knowledge - Connector Tools"]}}}}
```
# Delete a connector tool
Delete a specific tool by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connector Tools","description":"Endpoints for managing tools on an agent connector"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connector_tools.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/tools/{tool_id}":{"delete":{"description":"Delete a specific tool by its ID.","operationId":"delete-agent-connector-tools-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the parent connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of the tool","in":"path","name":"tool_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Tool successfully deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Server error"}},"summary":"Delete a connector tool","tags":["Knowledge - Connector Tools"]}}}}
```
# Run a connector tool
Execute a tool action. Returns the raw response from the upstream API endpoint.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Knowledge - Connector Tools","description":"Endpoints for managing tools on an agent connector"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"knowledge_connector_tools.BizAIOmniChannelConnectorToolRunRequest":{"description":"Execute a tool action","properties":{"input":{"description":"JSON-encoded input payload for the tool action. Defaults to empty object if not provided.","type":"string"}},"type":"object"},"knowledge_connector_tools.BizAIOmniChannelConnectorToolRunResponse":{"description":"The result of executing a tool action","properties":{"output":{"description":"JSON-encoded response from the tool execution","type":"string"},"status":{"description":"Execution status: success or error","type":"string"}},"required":["output","status"],"type":"object"},"knowledge_connector_tools.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_connectors/{connector_id}/tools/{tool_id}/run":{"post":{"description":"Execute a tool action. Returns the raw response from the upstream API endpoint.","operationId":"post-agent-connector-tools-run-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the parent connector","in":"path","name":"connector_id","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of the tool","in":"path","name":"tool_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRunRequest","summary":"requestBody","description":"Tool execution input"}}},"description":"Tool execution input","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.BizAIOmniChannelConnectorToolRunResponse"}}},"description":"The tool execution result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/knowledge_connector_tools.StandardError"}}},"description":"Server error"}},"summary":"Run a connector tool","tags":["Knowledge - Connector Tools"]}}}}
```
# Insights
Endpoints for retrieving the agent's usage insights
# Get agent event insights
Retrieve per-event-type volume, completion, and latency for the events sent to the agent over a date range, broken down by the event type supplied. Figures are rolled up once a day, so the most recent day may still be incomplete.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Insights","description":"Endpoints for retrieving the agent's usage insights"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"insights.AgentEventInsightsResponse":{"description":"The agent event insights for the requested range","properties":{"avg_e2e_latency_ms":{"description":"Mean time in milliseconds from receiving an event to the agent finishing with it, across every event type in the range. Null when nothing ran end to end","type":"number"},"data":{"description":"One row per event type received in the range, busiest first. Empty when no event of yours was received","items":{"$ref":"#/components/schemas/insights.BizAIOmniChannelAgentEventInsights"},"type":"array","uniqueItems":false}},"required":["data"],"type":"object"},"insights.BizAIOmniChannelAgentEventInsights":{"description":"Volume, completion, and latency for a single agent event type","properties":{"avg_e2e_latency_ms":{"description":"Mean time in milliseconds from receiving one of these events to the agent finishing with it, over every request in the range that ran end to end. Null when none did","type":"number"},"event_type":{"description":"The event type these figures cover, exactly as you sent it in the agent event request","type":"string"},"received":{"description":"Requests of this event type that arrived over the range, counted once each and summed across days","type":"integer"},"successfully_processed":{"description":"Requests of this event type the agent finished handling, summed across days. Requests that were turned away, skipped, or failed are not counted here. Finishing means the agent sent its message; it is not a delivery signal, and does not guarantee the message reached the customer device","type":"integer"}},"required":["event_type","received","successfully_processed"],"type":"object"},"insights.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/insights/agent_events":{"get":{"description":"Retrieve per-event-type volume, completion, and latency for the events sent to the agent over a date range, broken down by the event type supplied. Figures are rolled up once a day, so the most recent day may still be incomplete.","operationId":"get-agent-event-insights","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"First day to include, as YYYY-MM-DD in Pacific Time, which may differ from your own time zone. The boundary is inclusive.","in":"query","name":"start_date","required":true,"schema":{"type":"string"}},{"description":"Last day to include, as YYYY-MM-DD in Pacific Time, which may differ from your own time zone. The boundary is inclusive. start_date and end_date may span at most 30 days, counting both the first and last day.","in":"query","name":"end_date","required":true,"schema":{"type":"string"}},{"description":"Return only this event type, named as you sent it. Omit to get every event type received in the range.","in":"query","name":"event_type","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.AgentEventInsightsResponse"}}},"description":"The agent event insights for the requested range"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Server error"}},"summary":"Get agent event insights","tags":["Insights"]}}}}
```
# Get conversation insights
Retrieve how many conversations the AI agent handled over a date range, and how many are currently handed to the business awaiting a reply. Counts are per conversation, not per message. These are the same figures the business sees in their own agent summaries.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Insights","description":"Endpoints for retrieving the agent's usage insights"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"insights.ConversationInsightsResponse":{"description":"The conversation insights for the requested range","properties":{"data":{"description":"A single row covering the requested range. An array so a future per-day breakdown does not break callers","items":{"$ref":"#/components/schemas/insights.BizAIOmniChannelConversationInsights"},"type":"array","uniqueItems":false}},"required":["data"],"type":"object"},"insights.BizAIOmniChannelConversationInsights":{"description":"Conversation and handoff counts for the requested range","properties":{"ai_handoffs":{"$ref":"#/components/schemas/insights.BizAIOmniChannelConversationInsightsMetric","description":"Conversations currently handed from the AI agent to the business and still awaiting a business reply. This is a snapshot of the present moment, not a count over the requested range: it is the same figure whatever start_date and end_date you send. A conversation drops out of it once the business replies. Present only when the metric was requested"},"ai_threads":{"$ref":"#/components/schemas/insights.BizAIOmniChannelConversationInsightsMetric","description":"Conversations the AI agent replied in at least once between start_date and end_date, counted once however many messages each contains. Present only when the metric was requested"}},"type":"object"},"insights.BizAIOmniChannelConversationInsightsMetric":{"description":"A single conversation insights metric","properties":{"count":{"description":"The number of conversations this metric counts. What it counts, and whether the requested date range applies to it, is described on the metric itself","type":"integer"}},"required":["count"],"type":"object"},"insights.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/insights/conversations":{"get":{"description":"Retrieve how many conversations the AI agent handled over a date range, and how many are currently handed to the business awaiting a reply. Counts are per conversation, not per message. These are the same figures the business sees in their own agent summaries.","operationId":"get-conversation-insights","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"First day to include, as YYYY-MM-DD in the business time zone. The boundary is inclusive.","in":"query","name":"start_date","required":true,"schema":{"type":"string"}},{"description":"Last day to include, as YYYY-MM-DD in the business time zone. The boundary is inclusive. start_date and end_date may span at most 90 days, counting both the first and last day.","in":"query","name":"end_date","required":true,"schema":{"type":"string"}},{"description":"Which metrics to return. Defaults to all of them. Requesting only what you need is worthwhile: each metric costs a separate scan of the business's conversations.","in":"query","name":"metrics","schema":{"items":{"enum":["ai_handoffs","ai_threads"],"type":"string"},"type":"array"},"style":"form","explode":false}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.ConversationInsightsResponse"}}},"description":"The conversation insights for the requested range"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Server error"}},"summary":"Get conversation insights","tags":["Insights"]}}}}
```
# Get conversation turns
Retrieve the ordered turns from the most recent conversation with the specified user, identified by their phone number or Business-Scoped User ID (BSUID). Each turn includes a stable turn ID and the available observed steps. Latency, status, and model output fields are included only when available. Malformed records and tool responses that cannot be matched to a tool call may be omitted.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Insights","description":"Endpoints for retrieving the agent's usage insights"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"insights.ConversationTurnsResponse":{"description":"A paginated list of conversation turns","properties":{"data":{"description":"This array represents the page of data returned","items":{"$ref":"#/components/schemas/insights.BizAIOmniChannelConversationTurn"},"type":"array","uniqueItems":false},"paging":{"$ref":"#/components/schemas/pagination.Paging","description":"Cursor pagination"}},"required":["data"],"type":"object"},"insights.BizAIOmniChannelConversationTurn":{"description":"A single turn of a conversation with its observed steps","properties":{"conversation_id":{"description":"App-scoped opaque identifier for the conversation containing this turn","type":"string"},"e2e_latency_ms":{"description":"Elapsed time, in milliseconds, from when the agent receives the customer message that starts the turn until the agent finishes producing its response, including model and tool-call processing time, if available","type":"integer"},"message_id":{"description":"WhatsApp Cloud API message ID for the customer message that started the turn, reconstructed for the authorized consumer identity when available","type":"string"},"steps":{"description":"Ordered steps observed during the turn","items":{"$ref":"#/components/schemas/insights.BizAIOmniChannelConversationTurnStep"},"type":"array","uniqueItems":false},"timestamp":{"description":"Timestamp of the turn in milliseconds since epoch, if available","type":"integer"},"turn_id":{"description":"Stable identifier for the turn","type":"string"}},"required":["conversation_id","steps","turn_id"],"type":"object"},"insights.BizAIOmniChannelConversationTurnStep":{"description":"A single step observed during a conversation turn","properties":{"latency_ms":{"description":"Latency for the step in milliseconds, if available","type":"integer"},"llm_output_preview":{"description":"A truncated preview of the model output, for LLM calls","type":"string"},"status":{"description":"The step status: SUCCESS, ERROR, or TIMEOUT","enum":["SUCCESS","ERROR","TIMEOUT"],"type":"string"},"tool_input":{"description":"The input arguments passed to the tool, for tool calls","type":"string"},"tool_name":{"description":"The name of the tool used by this step, for tool calls","type":"string"},"tool_output":{"description":"The output returned by the tool, for tool calls","type":"string"},"type":{"description":"The type of step: LLM_CALL or TOOL_CALL","enum":["LLM_CALL","TOOL_CALL"],"type":"string"}},"required":["type"],"type":"object"},"pagination.Paging":{"description":"Cursor pagination. next/previous point back at this API; follow them directly, or page manually with the after/before query parameters","properties":{"cursors":{"$ref":"#/components/schemas/pagination.Cursors","description":"Page cursors"},"next":{"description":"URL of the next page as issued by Meta","type":"string"},"previous":{"description":"URL of the previous page as issued by Meta","type":"string"}},"type":"object"},"pagination.Cursors":{"properties":{"after":{"description":"Cursor of the next page","type":"string"},"before":{"description":"Cursor of the previous page","type":"string"}},"type":"object"},"insights.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/insights/conversations/turns":{"get":{"description":"Retrieve the ordered turns from the most recent conversation with the specified user, identified by their phone number or Business-Scoped User ID (BSUID). Each turn includes a stable turn ID and the available observed steps. Latency, status, and model output fields are included only when available. Malformed records and tool responses that cannot be matched to a tool call may be omitted.","operationId":"get-conversation-turns","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The consumer whose conversation turns should be retrieved. Accepts either a phone number in digits-only form (country code included, no leading +, spaces, or separators, e.g. 15551234567), or a Business-Scoped User ID (BSUID) - a stable per-business identifier WhatsApp assigns to a consumer, formatted . (e.g. US.2788620304833812). Any other phone-number formatting returns Consumer not found. Prefer 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. BSUIDs arrive in webhook payloads as messages[].from_user_id, message_echoes[].to_user_id, statuses[].recipient_user_id, contacts[].user_id, and state_sync[].contact.user_id. The conversation_id returned by the agent_test endpoint is also accepted. The server detects which type was provided based on the value format.","in":"query","name":"user_phone_number","required":true,"schema":{"type":"string"}},{"description":"Return turns that started at or after this Unix epoch timestamp in milliseconds. The boundary is inclusive.","in":"query","name":"start_timestamp_ms","schema":{"type":"integer"}},{"description":"Return turns that started at or before this Unix epoch timestamp in milliseconds. The boundary is inclusive.","in":"query","name":"end_timestamp_ms","schema":{"type":"integer"}},{"description":"If specified, a page of data immediately before this cursor will be returned","in":"query","name":"before","schema":{"type":"string"}},{"description":"If specified, a page of data immediately after this cursor will be returned","in":"query","name":"after","schema":{"type":"string"}},{"description":"The maximum number of objects that may be returned. A query may return fewer than this due to filtering, so use the absence of a next link rather than a short page to detect the end of the list","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.ConversationTurnsResponse"}}},"description":"The turns for the conversation"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Server error"}},"summary":"Get conversation turns","tags":["Insights"]}}}}
```
# Get tool call insights
Retrieve how each of your tools performed over a date range: how many conversations called it, how long it took to respond, and how often it succeeded, failed, or timed out. Only tools you supplied are reported. Figures are rolled up once a day, so the most recent day may still be incomplete.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Insights","description":"Endpoints for retrieving the agent's usage insights"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"insights.ToolCallInsightsResponse":{"description":"The tool call insights for the requested range","properties":{"data":{"description":"One row per tool called in the range, busiest first. Empty when no tool of yours was called","items":{"$ref":"#/components/schemas/insights.BizAIOmniChannelToolCallInsights"},"type":"array","uniqueItems":false}},"required":["data"],"type":"object"},"insights.BizAIOmniChannelToolCallInsights":{"description":"Call volume, latency, and health for a single tool","properties":{"avg_latency_ms":{"description":"Mean time the tool took to respond, in milliseconds, over every call in the range that was timed. Null when none were timed","type":"number"},"error_rate":{"description":"Share of calls that returned an error, between 0 and 1. Timeouts are errors, so they are included here as well as in timeout_rate. Null when no call in the range reported an outcome","maximum":1,"minimum":0,"type":"number"},"success_rate":{"description":"Share of calls that returned without an error, between 0 and 1. Null when no call in the range reported an outcome","maximum":1,"minimum":0,"type":"number"},"thread_count":{"description":"Conversations that called this tool, counted once per day and summed over the range. A conversation that called the tool on three separate days counts three times","type":"integer"},"timeout_rate":{"description":"Share of calls that timed out, between 0 and 1. A subset of error_rate. Null when no call in the range reported an outcome","maximum":1,"minimum":0,"type":"number"},"tool_name":{"description":"The tool these figures cover, as you named it when you registered it. Only tools you supplied are reported","type":"string"}},"required":["thread_count","tool_name"],"type":"object"},"insights.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/insights/tool_calls":{"get":{"description":"Retrieve how each of your tools performed over a date range: how many conversations called it, how long it took to respond, and how often it succeeded, failed, or timed out. Only tools you supplied are reported. Figures are rolled up once a day, so the most recent day may still be incomplete.","operationId":"get-tool-call-insights","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"First day to include, as YYYY-MM-DD in the business time zone. The boundary is inclusive.","in":"query","name":"start_date","required":true,"schema":{"type":"string"}},{"description":"Last day to include, as YYYY-MM-DD in the business time zone. The boundary is inclusive. start_date and end_date may span at most 30 days, counting both the first and last day.","in":"query","name":"end_date","required":true,"schema":{"type":"string"}},{"description":"Return only this tool, named as you registered it. Omit to get every tool that was called in the range.","in":"query","name":"tool_name","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.ToolCallInsightsResponse"}}},"description":"The tool call insights for the requested range"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Server error"}},"summary":"Get tool call insights","tags":["Insights"]}}}}
```
# UI Skills
Endpoints for managing the agent's UI skills - the rich message components it may send
# List UI skills
Retrieve all UI skills for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"UI Skills","description":"Endpoints for managing the agent's UI skills - the rich message components it may send"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"ui_skills.BizAIOmniChannelUISkillListResponse":{"description":"A paginated list of UI skills","properties":{"data":{"description":"The page of data returned","items":{"$ref":"#/components/schemas/ui_skills.BizAIOmniChannelUISkillResponse"},"type":"array","uniqueItems":false},"paging":{"$ref":"#/components/schemas/ui_skills.Paging","description":"Pagination metadata"}},"required":["data"],"type":"object"},"ui_skills.BizAIOmniChannelUISkillResponse":{"description":"A single UI skill","properties":{"component_type":{"description":"The type of rich message this UI skill sends","enum":["carousel_quick_reply","carousel_url","cta_url","flow","image","interactive_list","interactive_reply_buttons","location","location_request"],"type":"string"},"created_at":{"description":"The timestamp when the UI skill was created","type":"integer"},"flow_id":{"description":"The identifier of the associated flow. Only present for flow skills","type":"integer"},"id":{"description":"A unique identifier for the UI skill","type":"string"},"instruction":{"description":"A description telling the AI agent when to send this UI skill","type":"string"},"status":{"description":"Whether this UI skill is enabled and available to the AI agent","enum":["disabled","enabled"],"type":"string"},"title":{"description":"A human-readable name for the UI skill","type":"string"},"updated_at":{"description":"The timestamp when the UI skill was last updated","type":"integer"}},"required":["component_type","created_at","id","instruction","status","title","updated_at"],"type":"object"},"ui_skills.Paging":{"description":"Pagination metadata","properties":{"cursors":{"$ref":"#/components/schemas/ui_skills.Cursors","description":"Cursors to the next and previous pages"},"next":{"description":"The API that will return the next page of data. If not included, this is the last page of data. Due to how pagination works with visibility and privacy, a page may be empty but still carry a next link, so stop paging when the next link no longer appears","type":"string"},"previous":{"description":"The API that will return the previous page of data. If not included, this is the first page of data","type":"string"}},"required":["cursors"],"type":"object"},"ui_skills.Cursors":{"description":"Cursors to the next and previous pages","properties":{"after":{"description":"The cursor that points to the end of the page of data that has been returned","type":"string"},"before":{"description":"The cursor that points to the start of the page of data that has been returned","type":"string"}},"type":"object"},"ui_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-ui-skills":{"get":{"description":"Retrieve all UI skills for the specified entity.","operationId":"get-agent-ui-skills","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"If specified, a page of data immediately before this cursor will be returned","in":"query","name":"before","schema":{"type":"string"}},{"description":"If specified, a page of data immediately after this cursor will be returned","in":"query","name":"after","schema":{"type":"string"}},{"description":"The maximum number of objects that may be returned. A query may return fewer than this due to filtering, so use the absence of a next link rather than a short page to detect the end of the list","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.BizAIOmniChannelUISkillListResponse"}}},"description":"A paginated list of UI skills"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Server error"}},"summary":"List UI skills","tags":["UI Skills"]}}}}
```
# Create a UI skill
Create a new UI skill for the specified entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"UI Skills","description":"Endpoints for managing the agent's UI skills - the rich message components it may send"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"ui_skills.BizAIOmniChannelUISkillCreateRequest":{"description":"Create a UI skill","properties":{"component_type":{"description":"The type of rich message this UI skill sends","enum":["carousel_quick_reply","carousel_url","cta_url","flow","image","interactive_list","interactive_reply_buttons","location","location_request"],"type":"string"},"flow_id":{"description":"The identifier of the flow to associate. Required when component_type is flow, and not supported otherwise","type":"integer"},"instruction":{"description":"A description telling the AI agent when to send this UI skill","type":"string"},"status":{"description":"Whether this UI skill is enabled and available to the AI agent","enum":["disabled","enabled"],"type":"string"},"title":{"description":"A human-readable name for the UI skill","type":"string"}},"required":["component_type","instruction","status","title"],"type":"object"},"ui_skills.BizAIOmniChannelUISkillResponse":{"description":"A single UI skill","properties":{"component_type":{"description":"The type of rich message this UI skill sends","enum":["carousel_quick_reply","carousel_url","cta_url","flow","image","interactive_list","interactive_reply_buttons","location","location_request"],"type":"string"},"created_at":{"description":"The timestamp when the UI skill was created","type":"integer"},"flow_id":{"description":"The identifier of the associated flow. Only present for flow skills","type":"integer"},"id":{"description":"A unique identifier for the UI skill","type":"string"},"instruction":{"description":"A description telling the AI agent when to send this UI skill","type":"string"},"status":{"description":"Whether this UI skill is enabled and available to the AI agent","enum":["disabled","enabled"],"type":"string"},"title":{"description":"A human-readable name for the UI skill","type":"string"},"updated_at":{"description":"The timestamp when the UI skill was last updated","type":"integer"}},"required":["component_type","created_at","id","instruction","status","title","updated_at"],"type":"object"},"ui_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-ui-skills":{"post":{"description":"Create a new UI skill for the specified entity.","operationId":"post-agent-ui-skills","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.BizAIOmniChannelUISkillCreateRequest","summary":"requestBody","description":"UI skill to create"}}},"description":"UI skill to create","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.BizAIOmniChannelUISkillResponse"}}},"description":"The newly created UI skill"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Server error"}},"summary":"Create a UI skill","tags":["UI Skills"]}}}}
```
# Get a UI skill
Retrieve a single UI skill by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"UI Skills","description":"Endpoints for managing the agent's UI skills - the rich message components it may send"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"ui_skills.BizAIOmniChannelUISkillResponse":{"description":"A single UI skill","properties":{"component_type":{"description":"The type of rich message this UI skill sends","enum":["carousel_quick_reply","carousel_url","cta_url","flow","image","interactive_list","interactive_reply_buttons","location","location_request"],"type":"string"},"created_at":{"description":"The timestamp when the UI skill was created","type":"integer"},"flow_id":{"description":"The identifier of the associated flow. Only present for flow skills","type":"integer"},"id":{"description":"A unique identifier for the UI skill","type":"string"},"instruction":{"description":"A description telling the AI agent when to send this UI skill","type":"string"},"status":{"description":"Whether this UI skill is enabled and available to the AI agent","enum":["disabled","enabled"],"type":"string"},"title":{"description":"A human-readable name for the UI skill","type":"string"},"updated_at":{"description":"The timestamp when the UI skill was last updated","type":"integer"}},"required":["component_type","created_at","id","instruction","status","title","updated_at"],"type":"object"},"ui_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-ui-skills/{instruction_id}":{"get":{"description":"Retrieve a single UI skill by its ID.","operationId":"get-agent-ui-skills-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the UI skill","in":"path","name":"instruction_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.BizAIOmniChannelUISkillResponse"}}},"description":"The requested UI skill"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Server error"}},"summary":"Get a UI skill","tags":["UI Skills"]}}}}
```
# Update a UI skill
Update an existing UI skill by its ID. Only the fields present in the request are changed; the component type and the associated flow of a UI skill cannot be changed after it is created.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"UI Skills","description":"Endpoints for managing the agent's UI skills - the rich message components it may send"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"ui_skills.BizAIOmniChannelUISkillUpdateRequest":{"description":"Update a UI skill","properties":{"instruction":{"description":"A description telling the AI agent when to send this UI skill","type":"string"},"status":{"description":"Whether this UI skill is enabled and available to the AI agent. Flow skills cannot be enabled unless the corresponding flow is published","enum":["disabled","enabled"],"type":"string"},"title":{"description":"A human-readable name for the UI skill","type":"string"}},"type":"object"},"ui_skills.BizAIOmniChannelUISkillResponse":{"description":"A single UI skill","properties":{"component_type":{"description":"The type of rich message this UI skill sends","enum":["carousel_quick_reply","carousel_url","cta_url","flow","image","interactive_list","interactive_reply_buttons","location","location_request"],"type":"string"},"created_at":{"description":"The timestamp when the UI skill was created","type":"integer"},"flow_id":{"description":"The identifier of the associated flow. Only present for flow skills","type":"integer"},"id":{"description":"A unique identifier for the UI skill","type":"string"},"instruction":{"description":"A description telling the AI agent when to send this UI skill","type":"string"},"status":{"description":"Whether this UI skill is enabled and available to the AI agent","enum":["disabled","enabled"],"type":"string"},"title":{"description":"A human-readable name for the UI skill","type":"string"},"updated_at":{"description":"The timestamp when the UI skill was last updated","type":"integer"}},"required":["component_type","created_at","id","instruction","status","title","updated_at"],"type":"object"},"ui_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-ui-skills/{instruction_id}":{"put":{"description":"Update an existing UI skill by its ID. Only the fields present in the request are changed; the component type and the associated flow of a UI skill cannot be changed after it is created.","operationId":"put-agent-ui-skills-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the UI skill","in":"path","name":"instruction_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.BizAIOmniChannelUISkillUpdateRequest","summary":"requestBody","description":"Fields of the UI skill to update"}}},"description":"Fields of the UI skill to update","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.BizAIOmniChannelUISkillResponse"}}},"description":"The updated UI skill"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Server error"}},"summary":"Update a UI skill","tags":["UI Skills"]}}}}
```
# Delete a UI skill
Delete an existing UI skill by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"UI Skills","description":"Endpoints for managing the agent's UI skills - the rich message components it may send"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"ui_skills.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-ui-skills/{instruction_id}":{"delete":{"description":"Delete an existing UI skill by its ID.","operationId":"delete-agent-ui-skills-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The unique identifier of the UI skill","in":"path","name":"instruction_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The UI skill was deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ui_skills.StandardError"}}},"description":"Server error"}},"summary":"Delete a UI skill","tags":["UI Skills"]}}}}
```
# Operate
Endpoints for evaluating and operating the agent (eval jobs, events, and tests)
# List evaluation cases
List all evaluation scenario configurations for the given entity.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.EvalCasesResponse":{"description":"List of eval cases for the entity","properties":{"eval_cases":{"description":"Array of eval case configurations","items":{"$ref":"#/components/schemas/operate.BizAIEvalCaseResponse"},"type":"array","uniqueItems":false}},"required":["eval_cases"],"type":"object"},"operate.BizAIEvalCaseResponse":{"description":"A single evaluation scenario configuration","properties":{"categories":{"description":"Category strings for the test scenario","items":{"type":"string"},"type":"array","uniqueItems":false},"id":{"description":"The eval case entity ID","type":"string"},"max_turns":{"description":"Maximum number of turns allowed in the conversation simulation","type":"integer"},"scenario":{"description":"Free-form text defining the task and constraints for the user simulator","type":"string"},"success_criteria":{"description":"Criteria strings the agent must meet for the test to pass","items":{"type":"string"},"type":"array","uniqueItems":false}},"required":["id","scenario"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-eval/cases":{"get":{"description":"List all evaluation scenario configurations for the given entity.","operationId":"get-agent-eval-cases","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.EvalCasesResponse"}}},"description":"List of eval cases for the entity"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"List evaluation cases","tags":["Operate"]}}}}
```
# Get evaluation details
Retrieve per-conversation evaluation results by evaluation IDs.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.EvalDetailsResponse":{"description":"List of evaluation results","properties":{"evaluations":{"description":"List of evaluation results","items":{"$ref":"#/components/schemas/operate.BizAIEvalDetailResponse"},"type":"array","uniqueItems":false}},"required":["evaluations"],"type":"object"},"operate.BizAIEvalDetailResponse":{"description":"A per-conversation evaluation result","properties":{"creation_time":{"description":"Unix timestamp when the evaluation was created","type":"integer"},"custom_success_criteria":{"description":"JSON array of client-specified success criteria strings","type":"string"},"eval_case_id":{"description":"ID of the eval case that defined the scenario and success criteria","type":"string"},"id":{"description":"The evaluation ID","type":"string"},"per_turn_labels":{"description":"JSON array of per-turn label integers","type":"string"},"reasons":{"description":"JSON array of {category, score, description, recommended_actions} objects","type":"string"},"score":{"description":"Overall evaluation score from the judge LLM","type":"integer"},"transcript":{"description":"JSON object with system_prompt and transcript_turns for the evaluated conversation","type":"string"},"update_time":{"description":"Unix timestamp when the evaluation was last updated","type":"integer"}},"required":["creation_time","id","per_turn_labels","reasons","update_time"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-eval/details":{"get":{"description":"Retrieve per-conversation evaluation results by evaluation IDs.","operationId":"get-agent-eval-details","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"Comma-separated list of evaluation IDs to retrieve","in":"query","name":"eval_ids","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.EvalDetailsResponse"}}},"description":"The requested evaluations"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"Get evaluation details","tags":["Operate"]}}}}
```
# Get evaluation job status
Poll the status and results of a previously submitted evaluation job.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.BizAIComboJobStatusResponse":{"description":"Current job status and results (if completed)","properties":{"error":{"$ref":"#/components/schemas/operate.BizAIComboJobError"},"progress":{"$ref":"#/components/schemas/operate.BizAIComboJobProgress"},"result":{"$ref":"#/components/schemas/operate.BizAIComboJobResult"},"status":{"description":"Job status","enum":["QUEUED","RUNNING","COMPLETED","FAILED"],"type":"string"}},"required":["status"],"type":"object"},"operate.BizAIComboJobError":{"description":"Error details when status is FAILED","properties":{"code":{"description":"Error code (e.g. SIMULATION_FAILED)","type":"string"},"failed_case_ids":{"description":"IDs of cases that failed","items":{"type":"string"},"type":"array","uniqueItems":false},"message":{"description":"Human-readable error message","type":"string"}},"required":["code","message"],"type":"object"},"operate.BizAIComboJobProgress":{"description":"Progress information while the job is running","properties":{"completed":{"description":"Number of eval cases completed","type":"integer"},"current_stage":{"description":"Current pipeline stage","enum":["simulation","evaluation","insights","done"],"type":"string"},"total":{"description":"Total number of eval cases in the job","type":"integer"}},"required":["completed","current_stage","total"],"type":"object"},"operate.BizAIComboJobResult":{"description":"Full result payload when status is COMPLETED","properties":{"avg_conversation_score":{"description":"Average score across evaluated conversations (range: 1-5)","type":"number"},"avg_turn_score":{"description":"Average score across evaluated turns (range: 1-5)","type":"number"},"creation_time":{"description":"Unix timestamp when the insight report was created","type":"integer"},"eval_ids_by_score":{"description":"JSON object grouping evaluation IDs by score","type":"string"},"highlights":{"description":"JSON array of highlight objects with description and evaluation IDs","type":"string"},"summary":{"description":"Natural-language summary of overall agent performance","type":"string"},"summary_id":{"description":"The unique identifier for the summary report","type":"string"},"top_failure_categories":{"description":"JSON array of failure category objects with category, evaluation IDs, and recommended actions","type":"string"},"update_time":{"description":"Unix timestamp when the insight report was last updated","type":"integer"}},"required":["creation_time","summary","summary_id","update_time"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-eval/run":{"get":{"description":"Poll the status and results of a previously submitted evaluation job.","operationId":"get-agent-eval-run","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The job ID returned by the POST /run endpoint","in":"query","name":"job_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.BizAIComboJobStatusResponse"}}},"description":"Current job status and results (if completed)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"Get evaluation job status","tags":["Operate"]}}}}
```
# Run an evaluation job
Submit a combo evaluation job that runs simulation, evaluation, and optionally insights across multiple cases. Returns a job\_id for polling.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.BizAIComboRunRequest":{"description":"Combo evaluation job request body","type":"object"},"operate.BizAIComboRunResponse":{"description":"Acknowledgment that the job was accepted for processing","properties":{"job_id":{"description":"The unique identifier for the created evaluation job (pfbid format)","type":"string"},"status":{"description":"Initial job status: QUEUED","type":"string"}},"required":["job_id","status"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-eval/run":{"post":{"description":"Submit a combo evaluation job that runs simulation, evaluation, and optionally insights across multiple cases. Returns a job_id for polling.","operationId":"post-agent-eval-run","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"Comma-separated list of eval case IDs (pfbid format)","in":"query","name":"eval_case_ids","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.BizAIComboRunRequest","summary":"requestBody","description":"Combo evaluation job request body"}}},"description":"Combo evaluation job request body","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.BizAIComboRunResponse"}}},"description":"Acknowledgment that the job was accepted for processing"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"Run an evaluation job","tags":["Operate"]}}}}
```
# Get evaluation summary
Retrieve aggregated insight reports for agent evaluations by insight IDs.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.EvalSummariesResponse":{"description":"List of insight reports","properties":{"insights":{"description":"Array of insight report objects","items":{"$ref":"#/components/schemas/operate.BizAIEvalSummaryResponse"},"type":"array","uniqueItems":false}},"required":["insights"],"type":"object"},"operate.BizAIEvalSummaryResponse":{"description":"An aggregated insight report","properties":{"avg_conversation_score":{"description":"Average score across evaluated conversations","type":"number"},"avg_turn_score":{"description":"Average score across evaluated turns","type":"number"},"creation_time":{"description":"Unix timestamp when the insight report was created","type":"integer"},"eval_ids_by_score":{"description":"JSON object grouping evaluation IDs by score","type":"string"},"highlights":{"description":"JSON array of highlight objects with description and evaluation IDs","type":"string"},"id":{"description":"The unique identifier for the insight report","type":"string"},"summary":{"description":"Natural-language summary of overall agent performance","type":"string"},"top_failure_categories":{"description":"JSON array of failure category objects with category, evaluation IDs, and recommended actions","type":"string"},"update_time":{"description":"Unix timestamp when the insight report was last updated","type":"integer"}},"required":["creation_time","id","summary","update_time"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent-eval/summary":{"get":{"description":"Retrieve aggregated insight reports for agent evaluations by insight IDs.","operationId":"get-agent-eval-summary","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"Comma-separated list of summary IDs to retrieve","in":"query","name":"summary_ids","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.EvalSummariesResponse"}}},"description":"List of insight reports"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"Get evaluation summary","tags":["Operate"]}}}}
```
# Send an agent event
Trigger an agent action asynchronously. The event is enqueued for processing and the endpoint returns immediately with status "accepted".
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.BizAIOmniChannelAgentEventRequest":{"description":"Trigger an agent action asynchronously","properties":{"event":{"$ref":"#/components/schemas/operate.BizAIOmniChannelAgentEvent"},"to":{"description":"Consumer phone number in E.164 format","type":"string"}},"required":["event","to"],"type":"object"},"operate.BizAIOmniChannelAgentEvent":{"description":"Event-specific fields","properties":{"description":{"description":"Human-readable description of the event. Max 1024 characters.","type":"string"},"payload":{"description":"Opaque JSON string passed through to the agent as-is. Max 4096 characters.","type":"string"},"type":{"description":"Partner-defined event identifier, e.g. document_verified. Max 256 characters.","type":"string"}},"required":["description","payload","type"],"type":"object"},"operate.BizAIOmniChannelAgentEventResponse":{"description":"Acknowledgment that the event was accepted for processing","properties":{"agent_event_id":{"description":"The ID of the recorded agent event, when one was created","type":"string"},"status":{"description":"\"accepted\" when the event is successfully enqueued","type":"string"}},"required":["status"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_event":{"post":{"description":"Trigger an agent action asynchronously. The event is enqueued for processing and the endpoint returns immediately with status \"accepted\".","operationId":"post-agent-event","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.BizAIOmniChannelAgentEventRequest","summary":"requestBody","description":"Agent event to send"}}},"description":"Agent event to send","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.BizAIOmniChannelAgentEventResponse"}}},"description":"Acknowledgment that the event was accepted for processing"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"Send an agent event","tags":["Operate"]}}}}
```
# Get an agent event status
Retrieve the current processing status of a previously submitted agent event, identified by its ID.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.BizAIOmniChannelAgentEventStatusResponse":{"description":"The current processing status of an agent event","properties":{"created_at":{"description":"The ISO 8601 timestamp at which the agent event was received","type":"string"},"error_message":{"description":"Summary of failure, if event state is FAILED","type":"string"},"event_type":{"description":"The partner-defined event identifier supplied when the event was submitted, e.g. document_verified","type":"string"},"skipped_reason":{"description":"Summary of skip reason, if event state is SKIPPED","type":"string"},"status":{"description":"The current processing status of the agent event","enum":["request_received","processing","sent","failed","skipped","success"],"type":"string"},"updated_at":{"description":"The ISO 8601 timestamp at which the agent event status was last updated","type":"string"}},"required":["created_at","event_type","status","updated_at"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_event/{agent_event_id}":{"get":{"description":"Retrieve the current processing status of a previously submitted agent event, identified by its ID.","operationId":"get-agent-event-by-id","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The ID of the agent event, as returned by POST /agent_event","in":"path","name":"agent_event_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.BizAIOmniChannelAgentEventStatusResponse"}}},"description":"The current status of the agent event"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"Get an agent event status","tags":["Operate"]}}}}
```
# Run an agent test
Send a test message to the AI agent and receive a response. Messages are processed through the full agent pipeline without requiring a consumer phone number.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.BizAIOmniChannelAgentTestRequest":{"description":"Send a test message to the AI agent","properties":{"conversation_id":{"description":"Identifier for multi-turn test conversations. Provide the conversation_id from a previous response to continue that conversation.","type":"string"},"user_msg":{"description":"The text content of the test message to send to the AI agent","type":"string"}},"required":["user_msg"],"type":"object"},"operate.BizAIOmniChannelAgentTestResponse":{"description":"The AI agent response and test conversation metadata","properties":{"agent_response":{"description":"The AI agent response text","type":"string"},"conversation_id":{"description":"The test conversation identifier. Use this in subsequent requests for multi-turn conversations.","type":"string"},"handoff_reason":{"description":"If the agent hands off to a human, this contains the reason","type":"string"},"message_id":{"description":"Unique identifier for this message exchange","type":"string"},"no_response_reason":{"description":"If the agent did not generate a response, this contains the reason (e.g. ELIGIBILITY_CHECK_FAILED)","type":"string"},"product_variant_ids":{"description":"The variant IDs of the products referenced in the agent response","items":{"type":"string"},"type":"array","uniqueItems":false},"quick_replies":{"description":"Suggested quick reply messages generated by the AI agent","items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"description":"Unix timestamp when the response was generated","type":"integer"}},"required":["agent_response","conversation_id","message_id"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_test":{"post":{"description":"Send a test message to the AI agent and receive a response. Messages are processed through the full agent pipeline without requiring a consumer phone number.","operationId":"post-agent-test","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.BizAIOmniChannelAgentTestRequest","summary":"requestBody","description":"Test message to send"}}},"description":"Test message to send","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.BizAIOmniChannelAgentTestResponse"}}},"description":"Response containing the AI agent response and test conversation metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"Run an agent test","tags":["Operate"]}}}}
```
# Transfer thread control
Transfer thread control for a consumer conversation: release it back to Meta Business Agent as the automatic responder, pass it to Meta Business Agent or the configured escalation partner, or take it from the current owner.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Operate","description":"Endpoints for evaluating and operating the agent (eval jobs, events, and tests)"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"operate.ThreadControlRequest":{"description":"Thread control action to perform","properties":{"action":{"description":"The thread control action to perform. \"release\" relinquishes thread control and hands the conversation back to Meta Business Agent as the automatic responder; you must currently hold thread control. \"take\" acquires thread control from the current owner and is restricted to the configured escalation partner. \"pass\" transfers thread control to Meta Business Agent when control_pass.target_role is \"ai_agent\", or to the configured escalation partner when control_pass is omitted; you must currently hold thread control.","enum":["pass","release","take"],"type":"string"},"control_pass":{"$ref":"#/components/schemas/operate.ThreadControlPassRequest"},"messaging_product":{"description":"Messaging service used for the request. Must be \"whatsapp\".","enum":["whatsapp"],"type":"string"},"metadata":{"description":"Optional free-form string forwarded verbatim to the receiving app in the resulting messaging_handovers webhook.","type":"string"},"recipient":{"description":"Business-scoped user ID of the consumer whose thread control is being transferred. Accepted but not yet wired; provide \"to\" instead.","type":"string"},"to":{"description":"Consumer identifier (phone number or WhatsApp ID) whose thread control is being transferred.","type":"string"}},"required":["action","messaging_product"],"type":"object"},"operate.ThreadControlPassRequest":{"description":"Optional configuration for a pass action. When omitted, pass uses the configured escalation partner.","properties":{"target_role":{"description":"Role receiving thread control. \"ai_agent\" selects Meta Business Agent.","enum":["ai_agent"],"type":"string"}},"required":["target_role"],"type":"object"},"operate.ThreadControlResponse":{"description":"Thread control action result with messaging product identifier","properties":{"messaging_product":{"description":"Messaging service used for the response. Always \"whatsapp\".","enum":["whatsapp"],"type":"string"}},"required":["messaging_product"],"type":"object"},"operate.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_thread_control":{"post":{"description":"Transfer thread control for a consumer conversation: release it back to Meta Business Agent as the automatic responder, pass it to Meta Business Agent or the configured escalation partner, or take it from the current owner.","operationId":"post-agent-thread-control","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["1.0.0"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.ThreadControlRequest","summary":"requestBody","description":"Thread control action to perform"}}},"description":"Thread control action to perform","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.ThreadControlResponse"}}},"description":"Thread control action result with messaging product identifier"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/operate.StandardError"}}},"description":"Server error"}},"summary":"Transfer thread control","tags":["Operate"]}}}}
```
# Budget
Endpoints for managing the agent's usage budgets
# Get the agent budgets
Retrieve every budget currently configured for the agent. An empty budgets array means no cap is set and usage is unlimited.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Budget","description":"Endpoints for managing the agent's usage budgets"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"budget.AgentBudgetResponse":{"description":"The budgets configured for the agent","properties":{"budgets":{"description":"The budgets configured for the agent. When more than one is set, whichever is reached first takes effect. An empty array means no cap is set and usage is unlimited","items":{"$ref":"#/components/schemas/budget.AgentBudgetResponseItem"},"type":"array","uniqueItems":false}},"required":["budgets"],"type":"object"},"budget.AgentBudgetResponseItem":{"description":"A single budget configured for the agent","properties":{"budget_id":{"description":"Stable identifier for this budget. Pass it back on a subsequent set request to edit or preserve this budget","type":"string"},"max_budget":{"description":"The maximum allowed usage, in the given unit, within the time window","type":"integer"},"time_window":{"description":"The rolling period usage is totalled over, measured in the timezone of the WhatsApp Business Account","enum":["one_day","seven_days","fourteen_days","thirty_days"],"type":"string"},"unit_type":{"description":"What the budget measures: token usage or AI agent turns","enum":["token","ai_turn"],"type":"string"}},"required":["budget_id","max_budget","time_window","unit_type"],"type":"object"},"budget.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_budget/{entity_id}":{"get":{"description":"Retrieve every budget currently configured for the agent. An empty budgets array means no cap is set and usage is unlimited.","operationId":"get-agent-budget","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The ID of the entity that owns the agent - the Business Manager ID","in":"path","name":"entity_id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.AgentBudgetResponse"}}},"description":"The budgets currently configured for the agent"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Server error"}},"summary":"Get the agent budgets","tags":["Budget"]}}}}
```
# Replace the agent budgets
Replace the full set of budgets for the agent. The request describes the complete desired state, so any budget left out is removed, and an empty budgets array clears every budget and returns the agent to unlimited usage. To change an existing budget, pass back the budget\_id that was returned for it; the budget is updated in place and keeps its id. Omit budget\_id to add a new budget and have an id assigned.
```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.50.2"},"tags":[{"name":"Budget","description":"Endpoints for managing the agent's usage budgets"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"budget.AgentBudgetRequest":{"description":"Replace the full set of budgets for the agent","properties":{"budgets":{"description":"The complete set of budgets for the agent. This replaces any budgets already configured, so any left out are removed, and an empty array clears them all and returns the agent to unlimited usage. A given unit type and time window pair may only appear once","items":{"$ref":"#/components/schemas/budget.AgentBudgetRequestItem"},"type":"array","uniqueItems":false}},"required":["budgets"],"type":"object"},"budget.AgentBudgetRequestItem":{"description":"A single budget to configure for the agent","properties":{"budget_id":{"description":"Stable identifier of the budget. For an existing budget, pass the id the server returned when it was created to edit or preserve it. For a new budget, leave it empty; the server assigns one","type":"string"},"max_budget":{"description":"The maximum allowed usage, in the given unit, within the time window. Must be a positive whole number","minimum":1,"type":"integer"},"time_window":{"description":"The rolling period usage is totalled over, measured in the timezone of the WhatsApp Business Account","enum":["one_day","seven_days","fourteen_days","thirty_days"],"type":"string"},"unit_type":{"description":"What the budget measures: token usage or AI agent turns","enum":["token","ai_turn"],"type":"string"}},"required":["max_budget","time_window","unit_type"],"type":"object"},"budget.AgentBudgetResponse":{"description":"The budgets configured for the agent","properties":{"budgets":{"description":"The budgets configured for the agent. When more than one is set, whichever is reached first takes effect. An empty array means no cap is set and usage is unlimited","items":{"$ref":"#/components/schemas/budget.AgentBudgetResponseItem"},"type":"array","uniqueItems":false}},"required":["budgets"],"type":"object"},"budget.AgentBudgetResponseItem":{"description":"A single budget configured for the agent","properties":{"budget_id":{"description":"Stable identifier for this budget. Pass it back on a subsequent set request to edit or preserve this budget","type":"string"},"max_budget":{"description":"The maximum allowed usage, in the given unit, within the time window","type":"integer"},"time_window":{"description":"The rolling period usage is totalled over, measured in the timezone of the WhatsApp Business Account","enum":["one_day","seven_days","fourteen_days","thirty_days"],"type":"string"},"unit_type":{"description":"What the budget measures: token usage or AI agent turns","enum":["token","ai_turn"],"type":"string"}},"required":["budget_id","max_budget","time_window","unit_type"],"type":"object"},"budget.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/agent_budget/{entity_id}":{"post":{"description":"Replace the full set of budgets for the agent. The request describes the complete desired state, so any budget left out is removed, and an empty budgets array clears every budget and returns the agent to unlimited usage. To change an existing budget, pass back the budget_id that was returned for it; the budget is updated in place and keeps its id. Omit budget_id to add a new budget and have an id assigned.","operationId":"post-agent-budget","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["2.0.0"],"type":"string"}},{"description":"The ID of the entity that owns the agent - the Business Manager ID","in":"path","name":"entity_id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.AgentBudgetRequest","summary":"requestBody","description":"The complete set of budgets for the agent"}}},"description":"The complete set of budgets for the agent","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.AgentBudgetResponse"}}},"description":"The budgets configured for the agent after the update"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/budget.StandardError"}}},"description":"Server error"}},"summary":"Replace the agent budgets","tags":["Budget"]}}}}
```
---
[Next Page](https://docs.360dialog.com/docs/llms-full.txt/1)
.png?alt=media&token=670be96b-eba0-44dc-bc08-12343c5d6d4a){kind=link}
.png?alt=media&token=862b209a-55b1-4363-9d02-a7f2316fd724){kind=link}
.png?alt=media&token=121ca227-c4c1-4596-afa0-f012a47b7b42){kind=link}
