> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/mba/meta-business-agent/3.-configure-your-agent.md).

# 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**. A few things apply to all of them:

* **List endpoints return bare JSON arrays**, not a `{ "data": [ ... ] }` wrapper — and `settings` comes back as a single-element array. Lists come back complete, with no paging cursor.
* **Pass ids back exactly as the API returned them** (skill, FAQ, website, allowlist and connector ids). They aren't plain numbers or UUIDs, and reformatting them returns `404`.
* **`400` with the title `Content rejected`** means the text may go against Meta's Business AI policies. This applies to FAQs, skills and interactive messages. It isn't temporary: edit the content before sending it again.
* **`409 Conflict`** means another write changed the same number at the same time. Nothing was saved; retry the request as sent.
  {% endhint %}

{% hint style="info" %}
**Faster with the 360dialog MCP.** Configuration is mostly writing. With the [360dialog MCP](https://docs.360dialog.com/docs/mba/meta-business-agent/onboarding-options.md) connected, your AI assistant can draft business info, FAQs and skills from your website or documents and apply them for you.
{% 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: <YOUR_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](https://docs.360dialog.com/docs/mba/api-ref/knowledge-business-info/create-or-replace-business-information.md)

### 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: <YOUR_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](https://docs.360dialog.com/docs/mba/api-ref/knowledge-faq/create-an-faq.md)

{% hint style="warning" %}
**Updating an FAQ can change its id.** Always store the `id` from the update response and use it for later reads, updates and deletes — the id you sent may no longer exist.

* A `404` with the title `FAQ not found` means no FAQ with that id exists. On a delete, the entry is already gone, so treat it as done.
* If a retried update returns `404`, the first attempt probably succeeded and changed the id. List the FAQs and find the entry whose question and answer match what you sent.
  {% endhint %}

### 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.
* **Documents customers send in a chat are not read** by the agent. To ground the agent in a document, upload it here.
* To share files with users, use [interactive messages](#interactive-messages-ui-skills).
  {% endhint %}

```bash
curl --location 'https://waba-v2.360dialog.io/agent_config/files' \
--header 'D360-API-KEY: <YOUR_API_KEY>' \
--form 'file=@"/.../sample.pdf"' \
--form 'file_name="filename_001.pdf"'
```

[Upload a knowledge file](https://docs.360dialog.com/docs/mba/api-ref/knowledge-files/upload-a-knowledge-file.md)

**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.

```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_config/websites \
  -H "D360-API-KEY: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.example.com" }'
```

[Add a knowledge website](https://docs.360dialog.com/docs/mba/api-ref/knowledge-websites/add-a-knowledge-website.md)

Each entry reports how many pages were crawled and a `crawl_status`:

| `crawl_status`            | Meaning                                                                                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pending` / `in_progress` | The crawl hasn't finished yet.                                                                                                                                                 |
| `completed`               | The site was crawled and content was extracted.                                                                                                                                |
| `completed_no_data`       | The crawl worked, but nothing useful could be extracted — for example, no FAQ or business information pages. Point the agent at more specific pages, or add the facts as FAQs. |
| `failed`                  | No pages could be fetched at all. `crawl_error` gives the reason — for example, the site is unreachable or blocked by its `robots.txt`.                                        |

***

## 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" %}
**Meta now calls skills "agent instructions".** Only the name changed: the endpoint is still `/agent_config/skills` and the body still uses the `skill` field. The 360dialog Hub and this guide keep the name *Skills*.
{% endhint %}

{% 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: <YOUR_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](https://docs.360dialog.com/docs/mba/api-ref/knowledge-skills/create-a-skill.md)

#### Check that the skill is active

Every skill goes through an automated content review. The `status` field on create, read, update and list responses shows the result:

* **`active`** — passed review; the agent uses it.
* **`pending_review`** — the review is still running.
* **`blocked`** — didn't pass. The skill is saved and readable, but **the agent never applies it**.

{% hint style="warning" %}
**A `201 Created` doesn't mean the agent will use the skill.** Check `status` after creating or editing. Skills are most often blocked because the text asks for or refers to sensitive personal data, such as date of birth or national ID numbers. Edit the skill to remove that content and the review runs again.
{% endhint %}

### 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: <YOUR_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](https://docs.360dialog.com/docs/mba/webhooks.md).
  {% endhint %}

[Update AI agent settings](https://docs.360dialog.com/docs/mba/api-ref/onboarding/update-ai-agent-settings.md)

### 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. If an update leaves out `followup_interval_in_seconds`, the agent keeps its current interval.

{% 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](https://docs.360dialog.com/docs/mba/meta-business-agent/5.-go-live.md) and [Roll out to everyone](https://docs.360dialog.com/docs/mba/meta-business-agent/6.-roll-out-to-everyone.md).
{% endhint %}

```bash
curl -s -X PUT https://waba-v2.360dialog.io/agent_config/settings \
  -H "D360-API-KEY: <YOUR_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](https://docs.360dialog.com/docs/mba/api-ref/onboarding/update-ai-agent-settings.md)

### Interactive messages (UI Skills)

{% hint style="info" %}
**This step is optional.** Interactive messages 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.

Meta now calls UI Skills **interactive messages**. The endpoint and fields are unchanged.
{% endhint %}

Regular Skills tell the agent *how to think and respond*. **Interactive messages** tell it *when to reply with a rich WhatsApp component* instead of plain text — a button, an image, a video, a list, a carousel, a location share, or a Flow. Like Skills, each one 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 interactive message has:

* `title` — a human-readable name.
* `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 (HTTPS URL) and footer text                                 |
| `image`                     | A standalone image                                    | By URL or a previously uploaded media ID, with optional caption                         |
| `video`                     | A standalone video                                    | By HTTPS URL or a previously uploaded media ID, optional caption up to 1,024 characters |
| `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. Card images by URL only                 |
| `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: <YOUR_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."
  }'
```

A video example:

```bash
curl -s -X POST https://waba-v2.360dialog.io/agent-ui-skills \
  -H "D360-API-KEY: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "assembly-video",
    "component_type": "video",
    "status": "enabled",
    "instruction": "When a customer asks how to assemble or set up a bike they bought, send the assembly video from https://www.example.com/media/assembly.mp4 with the caption: \"Here is a 3-minute guide to assembling your bike.\""
  }'
```

[Create a UI skill](https://docs.360dialog.com/docs/mba/api-ref/ui-skills/create-a-ui-skill.md)

{% hint style="warning" %}

* **`component_type` and `flow_id` can't be changed after creation.** To change the message type, delete the interactive message and create a new one.
* **A `flow` interactive message can't be enabled until its Flow is published.** Publish the Flow first, then create or enable it.
* Only `title`, `status`, and `instruction` can be changed with an update — see [Update a UI skill](https://docs.360dialog.com/docs/mba/api-ref/ui-skills/update-a-ui-skill.md).
  {% 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`. See [Create a connector](https://docs.360dialog.com/docs/mba/api-ref/knowledge-connectors/create-a-connector.md) for every supported `auth_type`.

```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_connectors \
  -H "D360-API-KEY: <YOUR_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](https://docs.360dialog.com/docs/mba/api-ref/knowledge-connectors/create-a-connector.md)
{% 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/<CONNECTOR_ID>/tools \
  -H "D360-API-KEY: <YOUR_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](https://docs.360dialog.com/docs/mba/api-ref/knowledge-connector-tools/create-a-connector-tool.md)
{% endstep %}
{% endstepper %}

#### Pass the customer's phone number to your API

In a tool's `request_definition`, a field can be filled automatically with a macro instead of a value the agent has to ask for:

* `WHATSAPP_PHONE_NUMBER` — the customer's number in full E.164 format, e.g. `+60123456789`.
* `WHATSAPP_PHONE_NUMBER_NATIONAL` — the customer's number in local dialing form, for APIs that reject E.164: country code removed, national trunk prefix kept where the region has one. `+60123456789` is sent as `0123456789`. In regions without a trunk prefix, such as Singapore, only the country code is removed.

{% hint style="info" %}
**Read errors by status code, not by message text.** Connector and connector tool errors map to `400` (your integration rejected the request), `404` (the connector or tool doesn't exist), `429` (rate limited) and `500` (a failure on Meta's side). If you match on the text of `detail`, switch to the status code.
{% endhint %}

{% 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.360dialog.com/docs/mba/meta-business-agent/3.-configure-your-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
