WhatsApp

Status: آماده برای تولید از طریق WhatsApp Web (Baileys). Gateway مالک نشست(های) لینک‌شده است.

# نصب (در صورت نیاز)

• راه‌اندازی اولیه (openclaw onboard) و openclaw channels add --channel whatsapp هنگام اولین انتخاب WhatsApp plugin، نصب آن را پیشنهاد می‌کنند.
• openclaw channels login --channel whatsapp نیز وقتی plugin هنوز موجود نیست، جریان نصب را ارائه می‌دهد.
• کانال Dev + checkout گیت: به‌صورت پیش‌فرض از مسیر plugin محلی استفاده می‌کند.
• Stable/Beta: از بسته npm یعنی @openclaw/whatsapp روی تگ انتشار رسمی فعلی استفاده می‌کند.

نصب دستی همچنان در دسترس است:

openclaw plugins install @openclaw/whatsapp

برای دنبال کردن تگ انتشار رسمی فعلی، از بسته بدون نسخه استفاده کنید. نسخه دقیق را فقط زمانی pin کنید که به نصب بازتولیدپذیر نیاز دارید.

در Windows، WhatsApp plugin هنگام نصب npm به Git روی PATH نیاز دارد، چون یکی از وابستگی‌های Baileys/libsignal آن از یک URL گیت دریافت می‌شود. Git for Windows را نصب کنید، سپس shell را دوباره راه‌اندازی کنید و نصب را دوباره اجرا کنید:

winget install --id Git.Git -e

Portable Git نیز در صورتی کار می‌کند که دایرکتوری bin آن روی PATH باشد.

# راه‌اندازی سریع

{
channels: {
whatsapp: {
  dmPolicy: "pairing",
  allowFrom: ["+15551234567"],
  groupPolicy: "allowlist",
  groupAllowFrom: ["+15551234567"],
},
},
}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# الگوهای استقرار

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

# مدل زمان اجرا

• Gateway مالک سوکت WhatsApp و حلقه اتصال مجدد است.
• watchdog اتصال مجدد از فعالیت انتقال WhatsApp Web استفاده می‌کند، نه فقط حجم پیام‌های ورودی برنامه؛ بنابراین یک نشست دستگاه لینک‌شده کم‌صدا صرفا به این دلیل که اخیرا کسی پیامی نفرستاده است دوباره راه‌اندازی نمی‌شود. یک سقف طولانی‌تر سکوت برنامه همچنان اگر فریم‌های انتقال همچنان برسند ولی هیچ پیام برنامه‌ای در بازه watchdog پردازش نشود، اتصال مجدد را اجبار می‌کند؛ پس از یک اتصال مجدد گذرا برای نشستی که اخیرا فعال بوده، این بررسی سکوت برنامه برای نخستین پنجره بازیابی از timeout عادی پیام استفاده می‌کند.
• زمان‌بندی‌های سوکت Baileys به‌صورت صریح زیر web.whatsapp.* هستند: keepAliveIntervalMs pingهای برنامه WhatsApp Web را کنترل می‌کند، connectTimeoutMs timeout handshake آغازین را کنترل می‌کند، و defaultQueryTimeoutMs timeoutهای query در Baileys را کنترل می‌کند.
• ارسال‌های خروجی به یک شنونده فعال WhatsApp برای حساب مقصد نیاز دارند.
• ارسال‌های گروهی برای tokenهای @+<digits> و @<digits> در متن و captionهای رسانه، وقتی token با فراداده شرکت‌کننده فعلی WhatsApp مطابقت داشته باشد، از جمله گروه‌های پشتیبانی‌شده با LID، فراداده mention بومی را ضمیمه می‌کنند.
• چت‌های وضعیت و broadcast نادیده گرفته می‌شوند (@status، @broadcast).
• watchdog اتصال مجدد فعالیت انتقال WhatsApp Web را دنبال می‌کند، نه فقط حجم پیام‌های ورودی برنامه: نشست‌های دستگاه لینک‌شده کم‌صدا تا زمانی که فریم‌های انتقال ادامه دارند برقرار می‌مانند، اما توقف انتقال خیلی زودتر از مسیر قطع اتصال راه دور بعدی، اتصال مجدد را اجبار می‌کند.
• چت‌های مستقیم از قوانین نشست DM استفاده می‌کنند (session.dmScope؛ مقدار پیش‌فرض main، DMها را به نشست اصلی agent ادغام می‌کند).
• نشست‌های گروهی ایزوله هستند (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters می‌توانند با JID بومی @newsletter خود، مقصدهای خروجی صریح باشند. ارسال‌های خروجی newsletter به‌جای معنای نشست DM، از فراداده نشست کانال استفاده می‌کنند (agent:<agentId>:whatsapp:channel:<jid>).
• انتقال WhatsApp Web متغیرهای محیطی استاندارد proxy را روی میزبان Gateway رعایت می‌کند (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / گونه‌های lowercase). پیکربندی proxy در سطح میزبان را به تنظیمات proxy اختصاصی WhatsApp برای کانال ترجیح دهید.
• وقتی messages.removeAckAfterReply فعال باشد، OpenClaw پس از تحویل یک پاسخ قابل مشاهده، واکنش ack در WhatsApp را پاک می‌کند.

# hookهای Plugin و حریم خصوصی

پیام‌های ورودی WhatsApp می‌توانند شامل محتوای پیام شخصی، شماره تلفن‌ها، شناسه‌های گروه، نام فرستنده‌ها، و فیلدهای هم‌بستگی نشست باشند. به همین دلیل، WhatsApp payloadهای hook ورودی message_received را برای plugins broadcast نمی‌کند مگر اینکه صریحا opt in کنید:

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

می‌توانید opt-in را به یک حساب محدود کنید:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

این را فقط برای pluginsی فعال کنید که به آن‌ها برای دریافت محتوای پیام ورودی WhatsApp و شناسه‌ها اعتماد دارید.

# کنترل دسترسی و فعال‌سازی

# رفتار شماره شخصی و چت با خود

وقتی شماره خود لینک‌شده نیز در allowFrom وجود داشته باشد، محافظت‌های چت با خود WhatsApp فعال می‌شوند:

• رد کردن read receiptها برای نوبت‌های چت با خود
• نادیده گرفتن رفتار auto-trigger مربوط به mention-JID که در غیر این صورت خودتان را ping می‌کند
• اگر messages.responsePrefix تنظیم نشده باشد، پاسخ‌های چت با خود به‌صورت پیش‌فرض [{identity.name}] یا [openclaw] هستند

# نرمال‌سازی پیام و زمینه

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

# تحویل، قطعه‌بندی، و رسانه

# نقل‌قول کردن پاسخ

WhatsApp از نقل‌قول بومی پاسخ پشتیبانی می‌کند، که در آن پاسخ‌های خروجی به‌صورت قابل مشاهده پیام ورودی را نقل‌قول می‌کنند. آن را با channels.whatsapp.replyToMode کنترل کنید.

پیش‌فرض "off" است. بازنویسی‌های هر حساب از channels.whatsapp.accounts.<id>.replyToMode استفاده می‌کنند.

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

# سطح واکنش

channels.whatsapp.reactionLevel کنترل می‌کند که عامل تا چه اندازه از واکنش‌های ایموجی در WhatsApp استفاده کند:

پیش‌فرض: "minimal".

بازنویسی‌های هر حساب از channels.whatsapp.accounts.<id>.reactionLevel استفاده می‌کنند.

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

# واکنش‌های تأیید

WhatsApp از واکنش‌های تأیید فوری هنگام رسید دریافت ورودی از طریق channels.whatsapp.ackReaction پشتیبانی می‌کند. واکنش‌های تأیید توسط reactionLevel کنترل می‌شوند — وقتی reactionLevel برابر "off" باشد، سرکوب می‌شوند.

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

یادداشت‌های رفتاری:

• بلافاصله پس از پذیرش ورودی ارسال می‌شود (پیش از پاسخ)
• شکست‌ها ثبت می‌شوند اما تحویل عادی پاسخ را مسدود نمی‌کنند
• حالت گروهی mentions در نوبت‌های فعال‌شده با اشاره واکنش نشان می‌دهد؛ فعال‌سازی گروهی always برای این بررسی به‌عنوان دورزننده عمل می‌کند
• WhatsApp از channels.whatsapp.ackReaction استفاده می‌کند (messages.ackReaction قدیمی اینجا استفاده نمی‌شود)

# چندحسابی و اعتبارنامه‌ها

# ابزارها، کنش‌ها، و نوشتن پیکربندی

• پشتیبانی ابزار عامل شامل کنش واکنش WhatsApp (react) است.
• دروازه‌های کنش:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• نوشتن پیکربندی آغازشده توسط کانال به‌طور پیش‌فرض فعال است (با channels.whatsapp.configWrites=false غیرفعال کنید).

# عیب‌یابی

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# اعلان‌های سیستم

WhatsApp از اعلان‌های سیستم به سبک Telegram برای گروه‌ها و گفت‌وگوهای مستقیم از طریق نگاشت‌های groups و direct پشتیبانی می‌کند.

سلسله‌مراتب تفکیک برای پیام‌های گروه:

نگاشت مؤثر groups ابتدا تعیین می‌شود: اگر حساب groups خودش را تعریف کند، به‌طور کامل جایگزین نگاشت ریشه groups می‌شود (بدون ادغام عمیق). سپس جست‌وجوی اعلان روی همان نگاشت واحد حاصل اجرا می‌شود:

1. اعلان سیستم ویژه گروه (groups["<groupId>"].systemPrompt): زمانی استفاده می‌شود که ورودی گروه مشخص در نگاشت وجود داشته باشد و کلید systemPrompt آن تعریف شده باشد. اگر systemPrompt یک رشته خالی ("") باشد، wildcard سرکوب می‌شود و هیچ اعلان سیستمی اعمال نمی‌شود.
2. اعلان سیستم wildcard گروه (groups["*"].systemPrompt): زمانی استفاده می‌شود که ورودی گروه مشخص به‌طور کامل در نگاشت غایب باشد، یا وقتی وجود دارد اما هیچ کلید systemPrompt تعریف نمی‌کند.

سلسله‌مراتب تفکیک برای پیام‌های مستقیم:

نگاشت مؤثر direct ابتدا تعیین می‌شود: اگر حساب direct خودش را تعریف کند، به‌طور کامل جایگزین نگاشت ریشه direct می‌شود (بدون ادغام عمیق). سپس جست‌وجوی اعلان روی همان نگاشت واحد حاصل اجرا می‌شود:

1. پرامپت سیستمی مخصوص گفت‌وگوی مستقیم (direct["<peerId>"].systemPrompt): زمانی استفاده می‌شود که ورودی همتای مشخص در نقشه وجود داشته باشد و کلید systemPrompt آن تعریف شده باشد. اگر systemPrompt یک رشتهٔ خالی ("") باشد، wildcard نادیده گرفته می‌شود و هیچ پرامپت سیستمی اعمال نمی‌شود.
2. پرامپت سیستمی wildcard برای گفت‌وگوی مستقیم (direct["*"].systemPrompt): زمانی استفاده می‌شود که ورودی همتای مشخص به‌طور کامل در نقشه وجود نداشته باشد، یا وجود داشته باشد اما هیچ کلید systemPrompt تعریف نکند.

تفاوت با رفتار چندحسابی Telegram: در Telegram، groups ریشه عمداً برای همهٔ حساب‌ها در یک راه‌اندازی چندحسابی نادیده گرفته می‌شود - حتی حساب‌هایی که هیچ groups مخصوص خودشان تعریف نکرده‌اند - تا از دریافت پیام‌های گروه‌هایی که bot عضو آن‌ها نیست جلوگیری شود. WhatsApp این محافظ را اعمال نمی‌کند: groups ریشه و direct ریشه همیشه توسط حساب‌هایی که override در سطح حساب تعریف نکرده‌اند به ارث برده می‌شوند، فارغ از اینکه چند حساب پیکربندی شده باشد. در یک راه‌اندازی چندحسابی WhatsApp، اگر پرامپت‌های گروه یا گفت‌وگوی مستقیم مخصوص هر حساب می‌خواهید، به‌جای تکیه بر پیش‌فرض‌های سطح ریشه، نقشهٔ کامل را صریحاً زیر هر حساب تعریف کنید.

رفتار مهم:

• channels.whatsapp.groups هم نقشهٔ پیکربندی برای هر گروه است و هم allowlist گروه در سطح chat. در محدودهٔ ریشه یا حساب، groups["*"] یعنی «همهٔ گروه‌ها برای این محدوده پذیرفته می‌شوند».
• فقط زمانی wildcard گروه systemPrompt اضافه کنید که از قبل می‌خواهید آن محدوده همهٔ گروه‌ها را بپذیرد. اگر همچنان می‌خواهید فقط مجموعهٔ ثابتی از شناسه‌های گروه واجد شرایط باشند، از groups["*"] برای پیش‌فرض پرامپت استفاده نکنید. به‌جای آن، پرامپت را روی هر ورودی گروهی که صریحاً در allowlist است تکرار کنید.
• پذیرش گروه و مجوز فرستنده دو بررسی جداگانه هستند. groups["*"] مجموعهٔ گروه‌هایی را که می‌توانند به پردازش گروه برسند گسترش می‌دهد، اما به‌تنهایی هر فرستنده‌ای را در آن گروه‌ها مجاز نمی‌کند. دسترسی فرستنده همچنان جداگانه توسط channels.whatsapp.groupPolicy و channels.whatsapp.groupAllowFrom کنترل می‌شود.
• channels.whatsapp.direct همین اثر جانبی را برای DMها ندارد. direct["*"] فقط پس از آنکه یک DM از طریق dmPolicy به‌همراه allowFrom یا قواعد pairing-store پذیرفته شد، یک پیکربندی پیش‌فرض برای گفت‌وگوی مستقیم فراهم می‌کند.

مثال:

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "[email protected]": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

# اشاره‌گرهای مرجع پیکربندی

مرجع اصلی:

• مرجع پیکربندی - WhatsApp

فیلدهای مهم WhatsApp:

• دسترسی: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• تحویل: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• چندحسابی: accounts.<id>.enabled, accounts.<id>.authDir, overrideهای سطح حساب
• عملیات: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• رفتار نشست: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• پرامپت‌ها: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# مرتبط

• جفت‌سازی
• گروه‌ها
• امنیت
• مسیریابی کانال
• مسیریابی چندعاملی
• عیب‌یابی