---
read_when:
    - Налаштування саме груп WhatsApp
    - Змінення режимів активації WhatsApp (`mention` і `always`)
    - Налаштування ключів групових сеансів WhatsApp або контексту повідомлень, що очікують на обробку
sidebarTitle: WhatsApp groups
summary: Обробка групових повідомлень WhatsApp — активація, списки дозволених, сеанси та впровадження контексту
title: Групові повідомлення WhatsApp
x-i18n:
    generated_at: "2026-07-16T17:38:50Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: bd1adb379a4cae4ee9b4b9950d7519e62e1fc0e72ece25ec1b337ee3cb803cda
    source_path: channels/group-messages.md
    workflow: 16
---

Для моделі міжканальних груп (Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, Zalo) див. [Групи](/uk/channels/groups). На цій сторінці описано специфічну для WhatsApp поведінку на додачу до цієї моделі: активацію, списки дозволених груп, ключі сеансів для окремих груп і додавання контексту повідомлень, що очікують на обробку.

Мета: дозволити OpenClaw бути присутнім у групах WhatsApp, активуватися лише після згадки і зберігати цю гілку окремо від особистого сеансу приватних повідомлень.

<Note>
`agents.list[].groupChat.mentionPatterns` використовується спільно з перевіркою згадок в інших каналах. У конфігураціях із кількома агентами задайте його для кожного агента або використовуйте `messages.groupChat.mentionPatterns` як глобальне резервне значення. Якщо не задано жодного з них, шаблони формуються з імені або емодзі ідентичності агента.
</Note>

## Поведінка

- Режими активації: `mention` (типово) або `always`. `mention` вимагає звернення: справжньої @-згадки WhatsApp (`mentionedJids`), налаштованого шаблону регулярного виразу, цифр номера бота у форматі E.164 у будь-якому місці тексту або відповіді з цитуванням одного з повідомлень бота (крім конфігурацій чату із самим собою зі спільним номером). `always` активує агента для кожного повідомлення, але додана групова підказка наказує йому відповідати лише тоді, коли це корисно, а в інших випадках повертати точний токен мовчання `NO_REPLY` без урахування регістру. Типові значення беруться з конфігурації (`channels.whatsapp.groups` `requireMention`) і можуть бути перевизначені для кожної групи через `/activation`.
- Список дозволених груп: якщо задано `channels.whatsapp.groups`, допускаються лише зазначені JID груп (додайте `"*"`, щоб дозволити всі); повідомлення з груп поза списком відкидаються з підказкою в журналі.
- Політика груп: `channels.whatsapp.groupPolicy` визначає, чи приймаються групові повідомлення (`open|disabled|allowlist`). `allowlist` використовує `channels.whatsapp.groupAllowFrom` (резервне значення: явно задане `channels.whatsapp.allowFrom`). Типове значення — `allowlist` (заблоковано, доки ви не додасте відправників).
- Сеанси для окремих груп: ключі сеансів мають вигляд `agent:<agentId>:whatsapp:group:<jid>` (для облікових записів, що не є типовими, додається `:thread:whatsapp-account-<accountId>`), тому директиви на кшталт `/verbose on`, `/trace on` або `/think high` (надіслані як окремі повідомлення) діють лише в межах цієї групи; стан особистих приватних повідомлень не змінюється.
- Додавання контексту: **лише повідомлення, що очікують на обробку**, у групі (типово 50), які _не_ запустили виконання, додаються з префіксом у розділі `[Chat messages since your last reply - for context]`, а рядок, що спричинив запуск, — у розділі `[Current message - respond to this]`. Після виконання вікно очікування очищується; повідомлення, які вже є в сеансі, повторно не додаються.
- Атрибуція відправника: кожен рядок групи містить позначку відправника в конверті повідомлення, наприклад `[WhatsApp <groupJid> <timestamp>] Alice (+447700900123): text`, а ідентичність відправника разом із темою групи та її учасниками передається в ненадійному блоці метаданих розмови.
- Ефемерні повідомлення та повідомлення для одноразового перегляду: обгортки знімаються перед вилученням тексту й згадок, тому звернення всередині них усе одно спричиняють активацію.
- Системна підказка групи: під час першого ходу групового сеансу (і кожного ходу після того, як `/activation` змінює режим) до системної підказки додаються настанови щодо активації (`Activation: trigger-only ...` або `Activation: always-on ...`, а також «звертайтеся до конкретного відправника»). Постійні настанови щодо надсилання повідомлень у груповому чаті («Ви перебуваєте в груповому чаті WhatsApp…») додаються завжди.

## Приклад конфігурації (WhatsApp)

Забезпечте роботу звернень за відображуваним іменем, навіть коли WhatsApp вилучає видимий `@` із тексту повідомлення:

```json5
{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
      historyLimit: 50, // вікно контексту групи, що очікує на обробку (типово 50)
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}
```

Примітки:

- Регулярні вирази не враховують регістр і використовують ті самі обмеження безпечних регулярних виразів, що й інші поверхні регулярних виразів у конфігурації; некоректні шаблони та небезпечні вкладені повторення ігноруються.
- Коли хтось торкається контакту, WhatsApp усе одно надсилає канонічні згадки через `mentionedJids`, тому резервне визначення за номером потрібне рідко, але слугує корисною страховкою.
- Розмір вікна контексту, що очікує на обробку, визначається в такому порядку: `channels.whatsapp.accounts.<id>.historyLimit` → `channels.whatsapp.historyLimit` → `messages.groupChat.historyLimit` → 50.

### Команда активації (лише для власника)

Використовуйте команду групового чату:

- `/activation mention`
- `/activation always`

Змінювати це можуть лише номери власника (із `channels.whatsapp.allowFrom` або власний номер бота у форматі E.164, якщо значення не задано); `/activation` від будь-кого іншого ігнорується та зберігається лише як контекст. Надішліть `/status` як окреме повідомлення в групі, щоб переглянути поточний режим активації.

## Використання

1. Додайте свій обліковий запис WhatsApp (той, на якому працює OpenClaw) до групи.
2. Напишіть `@openclaw ...` (або додайте номер). Активувати агента можуть лише відправники зі списку дозволених, якщо не задано `groupPolicy: "open"`.
3. Підказка агента містить контекст групи, що очікує на обробку, а також рядки з позначками відправників, щоб агент міг звернутися до потрібної особи.
4. Директиви сеансу (`/verbose on`, `/trace on`, `/think high`, `/new` або `/reset`, `/compact`) застосовуються лише до сеансу цієї групи; надсилайте їх як окремі повідомлення, щоб вони були зареєстровані. Ваш особистий сеанс приватних повідомлень залишається незалежним.

## Тестування та перевірка

- Ручна базова перевірка:
  - Надішліть у групі звернення `@openclaw` і переконайтеся, що відповідь посилається на ім'я відправника.
  - Надішліть друге звернення й переконайтеся, що блок історії додано, а під час наступного ходу його очищено.
- Перевірте журнали Gateway (запустіть із `--verbose`) на наявність записів `inbound web message`, які містять `from: <groupJid>` і текст із позначкою відправника.

## Відомі особливості

- Heartbeats виконуються в основному сеансі агента; у групових сеансах запуски Heartbeat ніколи не виконуються.
- Механізм придушення відлуння запам'ятовує об'єднану підказку (історію та поточне повідомлення) для кожного сеансу, щоб доставлені повідомлення самого бота не спричиняли повторну активацію; ідентичний повторно надісланий пакет може бути пропущений як відлуння.
- Записи сховища сеансів відображаються як `agent:<agentId>:whatsapp:group:<jid>` у сховищі сеансів SQLite відповідного агента; відсутність запису лише означає, що група ще не спричиняла запуск.
- Індикатори введення тексту керуються `session.typingMode` / `agents.defaults.typingMode`. Коли для видимих відповідей увімкнено режим надсилання лише через інструмент повідомлень, індикатор введення типово з'являється відразу, щоб учасники групи бачили роботу агента, навіть якщо автоматичну остаточну відповідь не буде опубліковано. Явна конфігурація режиму введення тексту все одно має пріоритет.

## Пов’язані матеріали

- [Групи](/uk/channels/groups)
- [Маршрутизація каналів](/uk/channels/channel-routing)
- [Групи трансляції](/uk/channels/broadcast-groups)
