> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roll out safely

> Enable Meta Business Agent in stages, verify each settings change, and keep a tested rollback request ready.

Rollout has two independent controls: `rollout.enabled` determines whether the agent is enabled, and `ai_audience` determines who can receive agent replies.

**API reference:** [GET Get Settings](/api-reference/meta-business-agents/get-settings) · [PUT Replace Settings](/api-reference/meta-business-agents/replace-settings)

## Enable the agent for allowlisted recipients

Keep the audience restricted during the first live WhatsApp tests.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/settings" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "rollout": {"enabled": true},
    "ai_audience": "ALLOWLISTED_ONLY"
  }'
```

Send representative messages from every allowlisted test number and confirm that non-allowlisted numbers do not receive agent replies.

## Read back the effective settings

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/settings" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

The response is an array even when only one settings object exists. Verify both `rollout.enabled` and `ai_audience` after every rollout change.

## Set agent budgets

Budgets cap token or AI-turn usage over a rolling time window. YCloud uses the WhatsApp Business Phone Number ID to find the associated Business Manager.

**API reference:** [GET Get Budgets](/api-reference/meta-business-agents/get-budgets) · [PUT Replace Budgets](/api-reference/meta-business-agents/replace-budgets)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/budgets" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "budgets": [
      {
        "unit_type": "token",
        "time_window": "one_day",
        "max_budget": 10000
      },
      {
        "unit_type": "ai_turn",
        "time_window": "seven_days",
        "max_budget": 500
      }
    ]
  }'
```

`unit_type` is `token` or `ai_turn`. `time_window` is `one_day`, `seven_days`, `fourteen_days`, or `thirty_days`. `max_budget` must be a positive integer.

`PUT` replaces the complete Budget collection. Include `budget_id` for every existing Budget you want to keep, and omit it for a new Budget. Each `(unit_type, time_window)` pair must be unique. Send `{"budgets":[]}` to remove all limits. Read the collection back after every replacement.

## Expand to the full audience

Change only the audience after the allowlisted rollout passes acceptance testing.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/settings" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"ai_audience":"EVERYONE"}'
```

Omitted settings are left unchanged by YCloud. Read the settings again and monitor real conversations before treating the rollout as complete.

## Roll back when required

Keep this request ready before expanding the audience:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/settings" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "rollout": {"enabled": false},
    "ai_audience": "ALLOWLISTED_ONLY"
  }'
```

Read the effective settings after rollback. Disabling rollout does not delete the agent, knowledge, skills, or connectors.

<Warning>
  Enabling rollout changes live message handling. Coordinate ownership with human support teams and do not use the full audience as a substitute for completing restricted acceptance testing.
</Warning>

<Card title="Next: Operate and troubleshoot" icon="arrow-right" href="/en/documentation/meta-business-agent/operate-and-troubleshoot">
  Control live conversations, process events, inspect logs, and handle failures after launch.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.