WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Instal (sesuai kebutuhan)

• Onboarding (openclaw onboard) dan openclaw channels add --channel whatsapp meminta untuk memasang Plugin WhatsApp saat pertama kali Anda memilihnya.
• openclaw channels login --channel whatsapp juga menawarkan alur instal saat Plugin belum tersedia.
• Kanal dev + checkout git: default ke jalur Plugin lokal.
• Stabil/Beta: menggunakan paket npm @openclaw/whatsapp pada tag rilis resmi saat ini.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

Penyiapan cepat

{
  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>

​

Pola deployment

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

​

Model runtime

• Gateway memiliki socket WhatsApp dan loop sambung ulang.
• Watchdog sambung ulang menggunakan aktivitas transport WhatsApp Web, bukan hanya volume pesan aplikasi masuk, sehingga sesi perangkat tertaut yang sepi tidak dimulai ulang hanya karena belum ada yang mengirim pesan baru-baru ini. Batas kesunyian aplikasi yang lebih panjang tetap memaksa sambung ulang jika frame transport terus datang tetapi tidak ada pesan aplikasi yang ditangani selama jendela watchdog; setelah sambung ulang sementara untuk sesi yang baru aktif, pemeriksaan kesunyian aplikasi tersebut menggunakan timeout pesan normal untuk jendela pemulihan pertama.
• Timing socket Baileys eksplisit di bawah web.whatsapp.*: keepAliveIntervalMs mengontrol ping aplikasi WhatsApp Web, connectTimeoutMs mengontrol timeout handshake pembuka, dan defaultQueryTimeoutMs mengontrol timeout kueri Baileys.
• Pengiriman keluar membutuhkan listener WhatsApp aktif untuk akun target.
• Pengiriman grup melampirkan metadata mention native untuk token @+<digits> dan @<digits> dalam teks dan caption media saat token cocok dengan metadata peserta WhatsApp saat ini, termasuk grup berbasis LID.
• Chat status dan broadcast diabaikan (@status, @broadcast).
• Watchdog sambung ulang mengikuti aktivitas transport WhatsApp Web, bukan hanya volume pesan aplikasi masuk: sesi perangkat tertaut yang sepi tetap aktif selama frame transport berlanjut, tetapi transport yang macet memaksa sambung ulang jauh sebelum jalur pemutusan jarak jauh yang lebih lambat.
• Chat langsung menggunakan aturan sesi DM (session.dmScope; default main menggabungkan DM ke sesi utama agen).
• Sesi grup diisolasi (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters dapat menjadi target keluar eksplisit dengan JID native @newsletter. Pengiriman newsletter keluar menggunakan metadata sesi kanal (agent:<agentId>:whatsapp:channel:<jid>) alih-alih semantik sesi DM.
• Transport WhatsApp Web menghormati variabel lingkungan proxy standar pada host gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / varian huruf kecil). Lebih baik gunakan konfigurasi proxy tingkat host daripada pengaturan proxy WhatsApp khusus kanal.
• Saat messages.removeAckAfterReply diaktifkan, OpenClaw menghapus reaksi ack WhatsApp setelah balasan yang terlihat terkirim.

​

Hook Plugin dan privasi

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

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

​

Kontrol akses dan aktivasi

​

Perilaku nomor pribadi dan self-chat

• lewati tanda terima baca untuk giliran self-chat
• abaikan perilaku pemicu otomatis mention-JID yang jika tidak akan melakukan ping ke diri sendiri
• jika messages.responsePrefix tidak disetel, balasan self-chat default ke [{identity.name}] atau [openclaw]

​

Normalisasi pesan dan konteks

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

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

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

​

Pengiriman, pemotongan, dan media

​

Kutipan balasan

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

​

Level reaksi

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

​

Reaksi pengakuan

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

• dikirim segera setelah pesan masuk diterima (pra-balasan)
• kegagalan dicatat di log tetapi tidak memblokir pengiriman balasan normal
• mode grup mentions bereaksi pada giliran yang dipicu mention; aktivasi grup always bertindak sebagai bypass untuk pemeriksaan ini
• WhatsApp menggunakan channels.whatsapp.ackReaction (messages.ackReaction legacy tidak digunakan di sini)

​

Multi-akun dan kredensial

​

Tool, tindakan, dan penulisan config

• Dukungan tool agen mencakup tindakan reaksi WhatsApp (react).
• Gerbang tindakan:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Penulisan config yang dimulai channel diaktifkan secara default (nonaktifkan melalui channels.whatsapp.configWrites=false).

​

Pemecahan masalah

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

​

Prompt sistem

1. Prompt sistem khusus grup (groups["<groupId>"].systemPrompt): digunakan saat entri grup spesifik ada di map dan kunci systemPrompt-nya didefinisikan. Jika systemPrompt adalah string kosong (""), wildcard ditekan dan tidak ada prompt sistem yang diterapkan.
2. Prompt sistem wildcard grup (groups["*"].systemPrompt): digunakan saat entri grup spesifik sama sekali tidak ada dari map, atau saat entri tersebut ada tetapi tidak mendefinisikan kunci systemPrompt.

1. Prompt sistem khusus direct (direct["<peerId>"].systemPrompt): digunakan ketika entri peer tertentu ada di map dan kunci systemPrompt-nya didefinisikan. Jika systemPrompt berupa string kosong (""), wildcard ditekan dan tidak ada prompt sistem yang diterapkan.
2. Prompt sistem wildcard direct (direct["*"].systemPrompt): digunakan ketika entri peer tertentu sama sekali tidak ada di map, atau ketika entri itu ada tetapi tidak mendefinisikan kunci systemPrompt.

• channels.whatsapp.groups adalah map konfigurasi per grup sekaligus allowlist grup tingkat chat. Pada cakupan root maupun akun, groups["*"] berarti “semua grup diterima” untuk cakupan tersebut.
• Tambahkan wildcard grup systemPrompt hanya ketika Anda memang ingin cakupan tersebut menerima semua grup. Jika Anda masih ingin hanya sekumpulan ID grup tetap yang memenuhi syarat, jangan gunakan groups["*"] untuk default prompt. Sebagai gantinya, ulangi prompt pada setiap entri grup yang di-allowlist secara eksplisit.
• Penerimaan grup dan otorisasi pengirim adalah pemeriksaan terpisah. groups["*"] memperluas kumpulan grup yang dapat mencapai penanganan grup, tetapi itu sendiri tidak mengotorisasi setiap pengirim di grup tersebut. Akses pengirim tetap dikendalikan secara terpisah oleh channels.whatsapp.groupPolicy dan channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct tidak memiliki efek samping yang sama untuk DM. direct["*"] hanya menyediakan konfigurasi chat direct default setelah DM sudah diterima oleh dmPolicy plus allowFrom atau aturan 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.
            "120363406415684625@g.us": {
              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." },
          },
        },
      },
    },
  },
}

​

Penunjuk referensi konfigurasi

• Referensi konfigurasi - WhatsApp

• akses: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• pengiriman: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-akun: accounts.<id>.enabled, accounts.<id>.authDir, override tingkat akun
• operasi: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• perilaku sesi: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompt: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

​

Terkait

• Pairing
• Grup
• Keamanan
• Perutean channel
• Perutean multi-agent
• Pemecahan masalah