Ctrlk
Get StartedStatus PagePartner Docs
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

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

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.

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:

{
  "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.

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.

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

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 and set your daily token budget with some headroom above your busiest day.

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.

Replace the agent budgets

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.

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:

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.

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.

Pair this with allowlist testing. Message the agent from an allowlisted number (see 4. Test your Agent), 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.

Previous6. Roll out to everyone
NextFAQ

Last updated

Was this helpful?