---
read_when:
    - پیکربندی اختصاصی گروه‌های WhatsApp
    - تغییر حالت‌های فعال‌سازی WhatsApp (`mention` در برابر `always`)
    - تنظیم کلیدهای نشست گروهی WhatsApp یا بافت پیام‌های در انتظار
sidebarTitle: WhatsApp groups
summary: مدیریت پیام‌های گروهی WhatsApp — فعال‌سازی، فهرست‌های مجاز، نشست‌ها و تزریق زمینه
title: پیام‌های گروهی WhatsApp
x-i18n:
    generated_at: "2026-07-16T15:27:58Z"
    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)، به [گروه‌ها](/fa/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>` و بدنه دارای برچسب فرستنده را نشان می‌دهند.

## ملاحظات شناخته‌شده

- Heartbeatها در نشست اصلی عامل اجرا می‌شوند؛ نشست‌های گروهی هرگز اجرای Heartbeat دریافت نمی‌کنند.
- جلوگیری از بازتاب، اعلان ترکیبی (تاریخچه + پیام فعلی) را برای هر نشست به خاطر می‌سپارد تا پیام‌های تحویل‌شده خود ربات دوباره آن را فعال نکنند؛ یک دسته تکراری و یکسان ممکن است به‌عنوان بازتاب نادیده گرفته شود.
- ورودی‌های مخزن نشست به‌شکل `agent:<agentId>:whatsapp:group:<jid>` در مخزن نشست SQLite مختص هر عامل ظاهر می‌شوند؛ نبود یک ورودی فقط به این معناست که گروه هنوز اجرایی را فعال نکرده است.
- نشانگرهای تایپ از `session.typingMode` / `agents.defaults.typingMode` پیروی می‌کنند. وقتی پاسخ‌های قابل‌مشاهده در حالت فقط ابزار پیام فعال شده باشند، تایپ به‌طور پیش‌فرض بلافاصله آغاز می‌شود تا اعضای گروه بتوانند فعالیت عامل را ببینند، حتی اگر هیچ پاسخ نهایی خودکاری ارسال نشود. پیکربندی صریح حالت تایپ همچنان اولویت دارد.

## مرتبط

- [گروه‌ها](/fa/channels/groups)
- [مسیریابی کانال](/fa/channels/channel-routing)
- [گروه‌های پخش](/fa/channels/broadcast-groups)