---
read_when:
    - پیکربندی اختصاصی گروه‌های WhatsApp
    - تغییر حالت‌های فعال‌سازی WhatsApp (`mention` در برابر `always`)
    - تنظیم کلیدهای جلسه گروه WhatsApp یا زمینه پیام‌های در انتظار
sidebarTitle: WhatsApp groups
summary: مدیریت پیام‌های گروهی WhatsApp — فعال‌سازی، فهرست‌های مجاز، نشست‌ها و تزریق زمینه
title: پیام‌های گروهی WhatsApp
x-i18n:
    generated_at: "2026-05-06T09:02:22Z"
    model: gpt-5.5
    provider: openai
    source_hash: 489f04ea9f4d0954f77eee4590d609383d5dc987eaaea5eb121b454620a2d0fe
    source_path: channels/group-messages.md
    workflow: 16
---

برای مدل گروه‌های چندکاناله (Discord، iMessage، Matrix، Microsoft Teams، Signal، Slack، Telegram، WhatsApp، Zalo)، [گروه‌ها](/fa/channels/groups) را ببینید. این صفحه رفتار ویژه WhatsApp را روی آن مدل پوشش می‌دهد: فعال‌سازی، فهرست‌های مجاز گروه، کلیدهای نشست برای هر گروه، و تزریق زمینه پیام‌های در انتظار.

هدف: اجازه دهید OpenClaw در گروه‌های WhatsApp حضور داشته باشد، فقط وقتی صدا زده شد بیدار شود، و آن رشته گفتگو را از نشست پیام مستقیم شخصی جدا نگه دارد.

<Note>
`agents.list[].groupChat.mentionPatterns` همچنین توسط Telegram، Discord، Slack، و iMessage استفاده می‌شود. برای راه‌اندازی‌های چندعاملی، آن را برای هر عامل تنظیم کنید، یا از `messages.groupChat.mentionPatterns` به‌عنوان جایگزین سراسری استفاده کنید.
</Note>

## رفتار

- حالت‌های فعال‌سازی: `mention` (پیش‌فرض) یا `always`. `mention` به یک فراخوانی نیاز دارد (منشن‌های واقعی WhatsApp از طریق `mentionedJids`، الگوهای regex امن، یا E.164 ربات در هر جای متن). `always` عامل را با هر پیام بیدار می‌کند، اما فقط وقتی باید پاسخ دهد که بتواند ارزش معناداری اضافه کند؛ در غیر این صورت توکن سکوت دقیق `NO_REPLY` / `no_reply` را برمی‌گرداند. پیش‌فرض‌ها را می‌توان در پیکربندی (`channels.whatsapp.groups`) تنظیم کرد و برای هر گروه از طریق `/activation` بازنویسی کرد. وقتی `channels.whatsapp.groups` تنظیم شده باشد، به‌عنوان فهرست مجاز گروه نیز عمل می‌کند (برای اجازه دادن به همه، `"*"` را اضافه کنید).
- سیاست گروه: `channels.whatsapp.groupPolicy` کنترل می‌کند که آیا پیام‌های گروه پذیرفته شوند یا نه (`open|disabled|allowlist`). `allowlist` از `channels.whatsapp.groupAllowFrom` استفاده می‌کند (جایگزین: `channels.whatsapp.allowFrom` صریح). پیش‌فرض `allowlist` است (تا وقتی فرستنده‌ها را اضافه نکنید مسدود می‌ماند).
- نشست‌های هر گروه: کلیدهای نشست شبیه `agent:<agentId>:whatsapp:group:<jid>` هستند، بنابراین فرمان‌هایی مانند `/verbose on`، `/trace on`، یا `/think high` (که به‌صورت پیام مستقل فرستاده می‌شوند) به همان گروه محدود می‌شوند؛ وضعیت پیام مستقیم شخصی دست‌نخورده می‌ماند. Heartbeatها برای رشته‌های گروهی رد می‌شوند.
- تزریق زمینه: پیام‌های گروهی **فقط در انتظار** (پیش‌فرض 50) که اجرای عامل را _فعال نکرده‌اند_ زیر `[Chat messages since your last reply - for context]` پیشوند می‌گیرند، و خط فعال‌کننده زیر `[Current message - respond to this]` می‌آید. پیام‌هایی که از قبل در نشست هستند دوباره تزریق نمی‌شوند.
- نمایش فرستنده: اکنون هر دسته گروهی با `[from: Sender Name (+E164)]` تمام می‌شود تا Pi بداند چه کسی صحبت می‌کند.
- گذرا/یک‌بارمشاهده: پیش از استخراج متن/منشن‌ها، آن‌ها را باز می‌کنیم، بنابراین فراخوانی‌های داخل آن‌ها همچنان فعال می‌شوند.
- اعلان سیستمی گروه: در نوبت اول یک نشست گروهی (و هر زمان که `/activation` حالت را تغییر دهد) یک متن کوتاه در اعلان سیستمی تزریق می‌کنیم، مانند `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), ... Activation: trigger-only ... Address the specific sender noted in the message context.` اگر فراداده در دسترس نباشد، همچنان به عامل می‌گوییم که این یک گفتگوی گروهی است.

## نمونه پیکربندی (WhatsApp)

یک بلوک `groupChat` به `~/.openclaw/openclaw.json` اضافه کنید تا فراخوانی با نام نمایشی حتی وقتی WhatsApp نشانه بصری `@` را از بدنه متن حذف می‌کند کار کند:

```json5
{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}
```

نکات:

- regexها به بزرگی و کوچکی حروف حساس نیستند و از همان محافظ‌های regex امنی استفاده می‌کنند که سطوح regex پیکربندی دیگر استفاده می‌کنند؛ الگوهای نامعتبر و تکرار تو در توی ناامن نادیده گرفته می‌شوند.
- وقتی کسی روی مخاطب می‌زند، WhatsApp همچنان منشن‌های کانونیکال را از طریق `mentionedJids` می‌فرستد، بنابراین جایگزین شماره به‌ندرت لازم است اما یک شبکه ایمنی مفید است.

### فرمان فعال‌سازی (فقط مالک)

از فرمان گفتگوی گروه استفاده کنید:

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

فقط شماره مالک (از `channels.whatsapp.allowFrom`، یا E.164 خود ربات وقتی تنظیم نشده باشد) می‌تواند این را تغییر دهد. برای دیدن حالت فعال‌سازی فعلی، `/status` را به‌صورت پیام مستقل در گروه بفرستید.

## روش استفاده

1. حساب WhatsApp خودتان (همان حسابی که OpenClaw را اجرا می‌کند) را به گروه اضافه کنید.
2. بگویید `@openclaw …` (یا شماره را اضافه کنید). فقط فرستنده‌های موجود در فهرست مجاز می‌توانند آن را فعال کنند، مگر اینکه `groupPolicy: "open"` را تنظیم کنید.
3. اعلان عامل شامل زمینه اخیر گروه به‌همراه نشانگر پایانی `[from: …]` خواهد بود تا بتواند شخص درست را مخاطب قرار دهد.
4. دستورهای سطح نشست (`/verbose on`، `/trace on`، `/think high`، `/new` یا `/reset`، `/compact`) فقط روی نشست همان گروه اعمال می‌شوند؛ آن‌ها را به‌صورت پیام‌های مستقل بفرستید تا ثبت شوند. نشست پیام مستقیم شخصی شما مستقل می‌ماند.

## آزمایش / تأیید

- بررسی دستی سبک:
  - یک فراخوانی `@openclaw` در گروه بفرستید و پاسخی را تأیید کنید که به نام فرستنده اشاره می‌کند.
  - فراخوانی دوم را بفرستید و بررسی کنید که بلوک تاریخچه اضافه شده و سپس در نوبت بعدی پاک شده باشد.
- لاگ‌های Gateway را بررسی کنید (با `--verbose` اجرا کنید) تا ورودی‌های `inbound web message` را ببینید که `from: <groupJid>` و پسوند `[from: …]` را نشان می‌دهند.

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

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

## مرتبط

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