WhatsApp

Status: siap produksi melalui WhatsApp Web (Baileys). Gateway memiliki sesi tertaut.

# 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.

Instal manual tetap tersedia:

openclaw plugins install @openclaw/whatsapp

Gunakan paket bare untuk mengikuti tag rilis resmi saat ini. Pin versi yang tepat hanya saat Anda membutuhkan instal yang dapat direproduksi.

Di Windows, Plugin WhatsApp membutuhkan Git pada PATH selama instal npm karena salah satu dependensi Baileys/libsignal diambil dari URL git. Instal Git for Windows, lalu mulai ulang shell dan jalankan ulang instal:

winget install --id Git.Git -e

Portable Git juga berfungsi jika direktori bin-nya ada di PATH.

# 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

Pesan masuk WhatsApp dapat berisi konten pesan pribadi, nomor telepon, pengidentifikasi grup, nama pengirim, dan kolom korelasi sesi. Karena itu, WhatsApp tidak menyiarkan payload hook message_received masuk ke Plugin kecuali Anda secara eksplisit memilih ikut:

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

Anda dapat membatasi pilihan ikut ke satu akun:

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

Aktifkan ini hanya untuk Plugin yang Anda percayai untuk menerima konten pesan WhatsApp masuk dan pengidentifikasi.

# Kontrol akses dan aktivasi

# Perilaku nomor pribadi dan self-chat

Saat nomor diri tertaut juga ada di allowFrom, pengaman self-chat WhatsApp aktif:

• 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

WhatsApp mendukung kutipan balasan native, di mana balasan keluar menampilkan kutipan pesan masuk. Kontrol dengan channels.whatsapp.replyToMode.

Default adalah "off". Override per akun menggunakan channels.whatsapp.accounts.<id>.replyToMode.

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

# Level reaksi

channels.whatsapp.reactionLevel mengontrol seberapa luas agen menggunakan reaksi emoji di WhatsApp:

Default: "minimal".

Override per akun menggunakan channels.whatsapp.accounts.<id>.reactionLevel.

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

# Reaksi pengakuan

WhatsApp mendukung reaksi ack langsung pada tanda terima masuk melalui channels.whatsapp.ackReaction. Reaksi ack dibatasi oleh reactionLevel — reaksi ditekan saat reactionLevel adalah "off".

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

Catatan perilaku:

• 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

WhatsApp mendukung prompt sistem bergaya Telegram untuk grup dan chat langsung melalui map groups dan direct.

Hierarki resolusi untuk pesan grup:

Map groups efektif ditentukan terlebih dahulu: jika akun mendefinisikan groups sendiri, map tersebut sepenuhnya menggantikan map groups root (tanpa deep merge). Pencarian prompt kemudian berjalan pada satu map yang dihasilkan:

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.

Hierarki resolusi untuk pesan langsung:

Map direct efektif ditentukan terlebih dahulu: jika akun mendefinisikan direct sendiri, map tersebut sepenuhnya menggantikan map direct root (tanpa deep merge). Pencarian prompt kemudian berjalan pada satu map yang dihasilkan:

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.

Perbedaan dari perilaku multi-akun Telegram: Di Telegram, root groups sengaja ditekan untuk semua akun dalam penyiapan multi-akun — bahkan akun yang tidak mendefinisikan groups sendiri — untuk mencegah bot menerima pesan grup untuk grup yang tidak diikutinya. WhatsApp tidak menerapkan pelindung ini: root groups dan root direct selalu diwarisi oleh akun yang tidak mendefinisikan override tingkat akun, terlepas dari berapa banyak akun yang dikonfigurasi. Dalam penyiapan WhatsApp multi-akun, jika Anda menginginkan prompt grup atau direct per akun, definisikan map lengkap di bawah setiap akun secara eksplisit alih-alih mengandalkan default tingkat root.

Perilaku penting:

• 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.

Contoh:

{
  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." },
          },
        },
      },
    },
  },
}

# Penunjuk referensi konfigurasi

Referensi utama:

• Referensi konfigurasi - WhatsApp

Field WhatsApp bernilai tinggi:

• 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