---
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 settings as a `render-component` form. Each field must have a unique `name` matching the schema field name (used as the state key and the `update-config` field key), a `type`, a `label` (plain English), and a `description` (from schema output). For selects, specify `options`. For all fields, set `defaultValue` from `get-config` (current value) or the schema default.

**Admin phones:**

Call `whatsapp-config action: list-admin-phones` and include the result as a `list` field in the form:
- `name: "adminPhones"`, `type: "list"`, `label: "Admin phone numbers"`
- `defaultValue`: the array returned by `list-admin-phones`
- `addMessage`: `"Add admin phone {{value}}"`
- `removeMessage`: `"Remove admin phone {{value}}"`
- `addPlaceholder`: `"+44..."`
- `description`: from the schema's `.describe()` metadata

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.
