> 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/controlling-your-agent.md).

# Controlling your Agent

Once your agent is live: see what it costs, cap what it can spend, step into a conversation yourself, and see exactly what it did on a given reply.

## Billing

MBA is billed by Meta directly to you, with no 360dialog markup. Charges are **postpaid**: usage is billed at the start of the following month — no prepayment, no mid-month charges. A payment method (a credit line, or a credit card where Meta has enabled it for your account) is required before the agent can answer everyone — see [Roll out to everyone](https://docs.360dialog.com/docs/mba/meta-business-agent/6.-roll-out-to-everyone.md).

{% hint style="warning" %}
**If your credit line hits 100% utilization, MBA access is suspended** until it's resolved. Track your spend and set a usage budget below to cap it before you get there.
{% endhint %}

MBA usage doesn't appear in the standard WhatsApp message billing analytics. To see what your agent is costing you before the invoice arrives, use the [usage insights endpoint](https://docs.360dialog.com/docs/mba/api-ref/insights/get-the-business-agent-usage-insights.md) described below.

### Track usage and spend

See how many messages and tokens your agent has been billed for, and what they cost, for any hour, day or month. The figures come straight from Meta and are the same ones used to calculate your invoice. Full request and response schema: [Get the business agent usage insights](https://docs.360dialog.com/docs/mba/api-ref/insights/get-the-business-agent-usage-insights.md).

You'll need your **billable account ID** (`entity_id`). Find it in Meta's **Billing Hub** under **Accounts > Meta Business Agent accounts**. It can't be retrieved through the API yet, so copy it once and keep it with your configuration.

```bash
curl -s -G "https://waba-v2.360dialog.io/insights/usage/<ENTITY_ID>" \
  -H "D360-API-KEY: <YOUR_API_KEY>" \
  -H "X-API-Version: 3.0.0" \
  --data-urlencode "start=1788217200" \
  --data-urlencode "end=1788476400" \
  --data-urlencode "granularity=DAY"
```

For an account in the Europe/Lisbon timezone, this returns one row per day from 1 to 3 September 2026. `end` is exclusive, so a range ending at midnight on 4 September stops before that day:

```json
{
  "usage": [
    { "start": 1788217200, "end": 1788303600, "billable_messages": 412, "billable_tokens": 905300, "cost": 18.11 },
    { "start": 1788303600, "end": 1788390000, "billable_messages": 388, "billable_tokens": 851200, "cost": 17.02 },
    { "start": 1788390000, "end": 1788476400, "billable_messages": 450, "billable_tokens": 990100, "cost": 19.80 }
  ]
}
```

**Parameters**

* `start` / `end` — the date range as Unix timestamps in seconds. `start` is inclusive, `end` is exclusive.
* `granularity` — `HOUR`, `DAY`, or `MONTH`. For `MONTH`, `start` must be the 1st of a month and `end` the last day of a month.
* `dimensions` *(optional)* — `sender_id` and/or `channel`, to split each bucket. `sender_id` is the Meta phone number ID, so use it to see spend per number.
* `sender_ids` / `channels` *(optional)* — restrict results to specific phone number IDs, or to `whatsapp`.
* `metric_types` *(optional)* — any of `billable_messages`, `billable_tokens`, `cost`. All three are returned by default.

An empty `usage` array means the agent had no billable usage in that range.

{% hint style="info" %}
**Good to know**

* **Billed tokens can be lower than the tokens the agent used.** Meta normalizes tokens so the cost per message stays consistent. The number you see here is the one on your invoice.
* **`cost` is in your Meta Business Agent account's currency**, and matches what Meta charges you.
* **Buckets follow your billable account's timezone**, so a day can be 23 or 25 hours long when daylight saving time changes.
  {% endhint %}

**Common checks**

* *Month-to-date spend:* `granularity=DAY` from the 1st of the month to today, then sum `cost`.
* *Last month's total:* `granularity=MONTH` for the previous month.
* *Which number costs most:* add `dimensions=sender_id`.

***

## 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 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.
* `start_date` / `end_date` *(optional)* — limit the budget to a campaign period. See [Campaign budgets](#campaign-budgets).

The budget endpoint takes your **Business Manager ID** (the business that owns the number's WABA) in the path. Any other business is refused with `403`.

Not sure what cap to set? Pull a week of `billable_tokens` with `granularity=DAY` from [Track usage and spend](#track-usage-and-spend) and set your daily token budget with some headroom above your busiest day.

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

```bash
curl -s -X POST https://waba-v2.360dialog.io/agent_budget/<BUSINESS_MANAGER_ID> \
  -H "D360-API-KEY: <YOUR_API_KEY>" \
  -H "X-API-Version: 2.0.0" \
  -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](https://docs.360dialog.com/docs/mba/api-ref/budget/replace-the-agent-budgets.md)

### Campaign budgets

To cap a campaign rather than a rolling period, add `start_date` and `end_date` (`YYYY-MM-DD`, in the WhatsApp Business Account's timezone). The budget then counts only usage from `start_date` onward and stops applying after `end_date`.

```json
{ "unit_type": "token", "time_window": "fourteen_days", "max_budget": 3000000, "start_date": "2026-11-23", "end_date": "2026-12-02" }
```

* `start_date` requires `end_date`, and the period between them can't be longer than `time_window` (so 30 days at most). A longer period is rejected.
* `end_date` on its own is allowed: the budget caps the rolling window as usual until that date, then stops applying.
* Budgets are unique on `unit_type`, `time_window` and campaign period together, so the same unit and window can appear more than once if each covers a different period. Budgets without dates keep capping the rolling window.

{% hint style="info" %}
**A budget caps usage; it doesn't report it.** It sets how much the agent can consume, not what it has used or what you'll pay. To see actual usage and cost, use [Track usage and spend](#track-usage-and-spend).
{% endhint %}

***

## Thread control

The agent is the primary responder: when a customer writes in and nobody holds the conversation, the agent picks it up. Your team or systems will sometimes need to step into a conversation it's handling, and hand it back afterward.

While the agent holds a conversation, the customer'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 customer's messages arrive on `messages` and the agent stays quiet.

When you're done, hand the conversation back with the Thread Control endpoint. You have two actions:

* **`pass` to the agent** hands control straight back to the agent. Set `control_pass.target_role` to `ai_agent`. You must currently hold the conversation.
* **`release`** gives up control and returns the conversation to **idle**. Nobody holds it until the customer's next message, which goes to the primary responder. Releasing a conversation that's already idle succeeds, so you don't need to check first.

```bash
curl -s -X POST "https://waba-v2.360dialog.io/agent_thread_control" \
  -H "D360-API-KEY: <YOUR_API_KEY>" \
  -H "X-API-Version: 1.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "action": "pass",
    "to": "15551234567",
    "control_pass": { "target_role": "ai_agent" },
    "metadata": "order-issue-resolved"
  }'
```

Send `to` as digits only, with the country code and no `+`, spaces or separators. To release instead, send `"action": "release"` without `control_pass`. `metadata` is optional: it's forwarded unchanged in the resulting `messaging_handovers` event.

A successful response includes a `request_id`. Keep it, and include it if you contact support about that call.

[Transfer thread control](https://docs.360dialog.com/docs/mba/api-ref/operate/transfer-thread-control.md)

A third action, `take`, is reserved for the number's configured escalation partner. You don't need it to step in: sending a message takes control.

**Good to know**

* **Only `pass` and `take` emit a `messaging_handovers` event.** `release` emits none. See [Webhooks](https://docs.360dialog.com/docs/mba/webhooks.md).
* **There's no endpoint to read who holds a conversation.** Track it yourself from the `standby` vs `messages` routing and the `messaging_handovers` events.
* **A conversation returns to idle after 24 hours without a customer message.** The customer's next message goes to the primary responder again.
* **Sending a template doesn't change who holds the conversation.** A customer tapping a button on a marketing or utility template, or clicking a click-to-WhatsApp ad, does re-route it.
* **Errors come from Meta unchanged.** We pass Meta's status code and body through as-is. A `2xx` response can still carry an `errors` object, so check the body, not just the status. 360dialog only adds `401` (invalid or missing API key), `400` (missing parameters) and `429` (rate limited).

***

## Agent events

An agent event asks the agent to message a customer proactively — for example, when a document is verified or an order ships. The event is queued and the endpoint answers immediately; poll its status by `agent_event_id`.

* **`to`** — the customer's phone number in E.164 format, or their BSUID (the `user_id` from your webhook) for customers whose phone number you don't have. The customer must already have a conversation with your business.
* **The agent must hold the conversation** for the event to be delivered.

When an event fails, its status `error_message` says why:

| `error_message`                  | Meaning                                                                                                                   |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `consumer_not_in_agent_audience` | The customer isn't in the agent's audience — for example, not on the allowlist while `ai_audience` is `ALLOWLISTED_ONLY`. |
| `agent_not_enabled`              | The agent is turned off for this number.                                                                                  |
| `thread_not_owned_by_agent`      | Someone else holds the conversation.                                                                                      |
| `event_content_rejected`         | The event text was declined.                                                                                              |
| `billing_not_configured`         | Payment method missing or billing details incomplete.                                                                     |
| `agent_temporarily_unavailable`  | Retry later.                                                                                                              |
| `internal_server_error`          | Any other failure.                                                                                                        |

The status also includes `conversation_id` once the agent has served the conversation, so you can look up the [turns](#conversation-turns) the agent took in response.

* [Send an agent event](https://docs.360dialog.com/docs/mba/api-ref/operate/send-an-agent-event.md)
* [Get an agent event status](https://docs.360dialog.com/docs/mba/api-ref/operate/get-an-agent-event-status.md)
* [Get agent event insights](https://docs.360dialog.com/docs/mba/api-ref/insights/get-agent-event-insights.md)

***

## 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: <YOUR_API_KEY>" \
  -H "X-API-Version: 2.0.0" \
  --data-urlencode "user_phone_number=<CUSTOMER_IDENTIFIER>"
```

`user_phone_number` is required and accepts any of:

* A phone number, **digits only**, country code included, no `+` or separators (e.g. `15551234567`).
* A **BSUID** (e.g. `US.2788620304833812`). Prefer it for any customer who has ever adopted a WhatsApp username — a phone-number lookup can return `Consumer not found` for them.
* The `conversation_id` returned by [`agent_test`](https://docs.360dialog.com/docs/mba/meta-business-agent/4.-test-your-agent.md).

You can optionally narrow the window with `start_timestamp_ms` / `end_timestamp_ms`, and page through results with `before` / `after` / `limit`.

Results can be filtered, so a page can be shorter than `limit`, or even empty, and still have more after it. Keep paging until the response no longer includes `paging.next`.

Each turn includes the fields below. `turn_id`, `conversation_id` and `steps` are always there; the others appear when available.

* `turn_id` — a stable identifier for the turn.
* `conversation_id` — the conversation this turn belongs to.
* `message_id` — the WhatsApp Cloud API message ID of the customer message that started the turn. Matches the ID on your `messages` webhook.
* `agent_event` — present when the turn was started by an [agent event](#agent-events) rather than a customer message: the `type`, `description` and `payload` you sent.
* `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`) and, when available, 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`.

[Get conversation turns](https://docs.360dialog.com/docs/mba/api-ref/insights/get-conversation-turns.md)

{% hint style="info" %}
**Pair this with testing.** Send a test message (see [4. Test your Agent](https://docs.360dialog.com/docs/mba/meta-business-agent/4.-test-your-agent.md)), then pull that conversation'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 to debug a reported issue.
{% endhint %}

To see the same turns and steps without an API call, use the **Conversation trace** card in the 360dialog Hub. Open the channel and go to Agent > **Live agent**. See [**Onboarding options**](https://docs.360dialog.com/docs/mba/meta-business-agent/onboarding-options.md) for what the card shows.


---

# 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/controlling-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.
