> 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 (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.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](/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](/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/" \ -H "D360-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`. [Get the business agent usage insights](/docs/mba/api-ref/insights/get-the-business-agent-usage-insights.md) *** ## 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. 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. 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.md) {% 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 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.md) 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 Agent](/docs/mba/meta-business-agent/4.-test-your-agent.md)), 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 %} --- # 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=&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.