---
name: manage-whatsapp-config
description: Guide the user through viewing and editing WhatsApp settings — messaging policies, operational limits, group config, and acknowledgement behaviour. Conversational, not a raw form dump.
---

# Manage WhatsApp Config

Conversational editing of WhatsApp settings. Every field is presented with its description, current value, and what the default means — the user makes informed decisions without needing backend knowledge.

## When to activate

User asks to change, view, edit, or manage WhatsApp settings, policies, limits, or group configuration. Also activate when the user asks about read receipts, message batching, media limits, or DM/group policies.

## Prerequisites

Call `whatsapp-status` first — if no WhatsApp account is connected, direct the user to the connect-whatsapp skill instead.

## Presenting settings

Call `whatsapp-config action: schema` to get field definitions with descriptions, and `whatsapp-config action: get-config` to get current values. Use the Description column from the schema output as the `description` field on each form field — do not improvise descriptions.

### Form fields

Present the settings to the operator as a numbered checklist in plain chat. For each field show the schema name, its label, the current value (from `get-config`) or the schema default, and the description from the schema output. For selects, list the available options. The operator replies with the changes they want, and the agent applies them via `whatsapp-config action: update-config`.

**Admin phones:**

Call `whatsapp-config action: list-admin-phones` and present the current list. Ask the operator which phones to add (`+44…` format) and which to remove. Apply each change via `whatsapp-config action: add-admin-phone` / `remove-admin-phone`. Confirm the resulting list to the operator after the writes land.

Each add/remove fires immediately — admin phones are managed per-action, independent of the form's batch submit.

**Public agent:**

Call `whatsapp-config action: list-public-agents` to get available agents, and `whatsapp-config action: get-public-agent` to get the current selection.

- `publicAgent` (`select`): label "Public agent for WhatsApp"
  - Options: one per agent from `list-public-agents` response — `value: slug`, `label: displayName`
  - `defaultValue`: the slug returned by `get-public-agent` (current selection)
  - `description`: from the schema's `.describe()` metadata for the `publicAgent` field
  - If `list-public-agents` returns an empty array, still include the field with no options and `description`: "No public agents available. Create one first using the public agent manager."

**Messaging policies:**

- `dmPolicy` (`select`): label "Who can message your agent (DMs)", options:
  - `open` — "Open — anyone can message"
  - `allowlist` — "Allowlist — only approved numbers"
  - `disabled` — "Disabled — no public DMs"
- `groupPolicy` (`select`): label "Group message handling", options:
  - `open` — "Always — respond to all group messages"
  - `allowlist` — "Allowlist — only in approved groups"
  - `disabled` — "Disabled — ignore all group messages"

**Behaviour:**

- `sendReadReceipts` (`select`): label "Blue ticks (read receipts)", options:
  - `true` — "On — contacts see read receipts"
  - `false` — "Off — no read receipts"

**Operational limits:**

- `mediaMaxMb` (`number`): label "Media size limit (MB)"
- `textChunkLimit` (`number`): label "Message chunk limit (characters)"
- `debounceMs` (`number`): label "Message batching delay (ms)", defaultValue `2000`

### Submit

The form's `submitMessage` must map the field values back to `update-config` field names: `Save these WhatsApp settings: {{json}}` — where `{{json}}` produces the JSON object with field names as keys (e.g. `{ "dmPolicy": "open", "mediaMaxMb": 50, ... }`).

## Group configuration

When the user wants to configure per-group settings:

1. Call `whatsapp-config action: list-groups` to get groups the account belongs to, with names and participant counts
2. If the account is not connected, explain that group discovery requires an active WhatsApp connection
3. If no groups are found, tell the user: "You're not in any WhatsApp groups on this account yet. Groups will appear here once the connected phone joins them."
4. Present groups by name (not by JID) — the user picks from a list
5. For each selected group, offer the activation options: 'always' (respond to every message), 'mention' (respond only when @mentioned), 'off' (silent)
6. Map the user's selections back to JIDs when writing config

## Writing changes

After the user submits, write changes via `whatsapp-config action: "update-config"` with the `fields` parameter containing a JSON object of the changed fields. Each field is merged individually — unchanged fields are left untouched. Confirm what changed — name each setting that was modified and its new value.

## Language

Plain English goes in `label` — schema field names go in `name`. The `name` property is the machine key (must match the schema exactly); the `label` is what the user reads. Examples:

- `name: "dmPolicy"`, `label: "Who can message your agent (DMs)"`
- `name: "debounceMs"`, `label: "Message batching delay (ms)"`
- `name: "mediaMaxMb"`, `label: "Media size limit (MB)"`
- `name: "sendReadReceipts"`, `label: "Blue ticks (read receipts)"`

Group names (not JIDs) in all user-facing text.
