# `bird whatsapp agents settings update`

## Usage

```bash
bird whatsapp agents settings update <number-id> [flags]
```

## Description

Update a WhatsApp agent's settings

Change how the agent behaves: turn it on or off, set who it may answer, how it hands over and follows up, and what it must never say. Omitted fields are left alone. The change is written to WhatsApp and saved once WhatsApp accepts it, and takes effect on the next conversation turn.

Build the request from flags, a JSON WhatsAppAgentSettingsUpdate body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

## Examples

```bash
# print the body shape (no credentials needed)
bird whatsapp agents settings update --example

# the body it prints:
```

```json
{
  "ai_audience": "allowlist",
  "enabled": true,
  "handoff": {
    "enabled": true,
    "message_selection": "agent"
  }
}
```

## Options

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                           | Description                                                                                                                                                                                                  |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--enabled`                    | Turn the agent on or off. Off stops it in every conversation at once and keeps everything it knows; on applies to conversations that start afterwards, not the ones already open. Omit to leave it as it is. |
| `--ai-audience`                | Who the agent may answer. Omit to leave it as it is. Possible values: everyone, allowlist.                                                                                                                   |
| `--never-say-phrases <value>…` | Wording the agent must never use. The list replaces the whole set, so send the phrases you want kept along with any you are adding, and send an empty list to clear it. Omit to leave it as it is.           |
| `--response-schema`            | Print the fields this command returns, then exit                                                                                                                                                             |

## Related

| Name                                                                                    | Description                     |
| --------------------------------------------------------------------------------------- | ------------------------------- |
| [`bird whatsapp agents settings get`](/docs/cli/reference/whatsapp-agents-settings-get) | Get a WhatsApp agent's settings |

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)