Roll out safely

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 · PUT Replace Settings

Enable the agent for allowlisted recipients

Keep the audience restricted during the first live WhatsApp tests.

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

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 · PUT Replace Budgets

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.

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:

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.

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.

Next: Operate and troubleshoot

Control live conversations, process events, inspect logs, and handle failures after launch.

Getting Started

Guides

Endpoints

Webhooks

Enable the agent for allowlisted recipients

Read back the effective settings

Set agent budgets

Expand to the full audience

Roll back when required

Next: Operate and troubleshoot

​Enable the agent for allowlisted recipients

​Read back the effective settings

​Set agent budgets

​Expand to the full audience

​Roll back when required

Next: Operate and troubleshoot

Enable the agent for allowlisted recipients

Read back the effective settings

Set agent budgets

Expand to the full audience

Roll back when required