WhatsApp

​

Instalasi (sesuai permintaan)

• Onboarding (openclaw onboard) dan openclaw channels add --channel whatsapp meminta Anda memasang Plugin WhatsApp saat pertama kali memilihnya.
• openclaw channels login --channel whatsapp juga menawarkan alur instalasi ketika Plugin belum tersedia.
• Channel dev + checkout git: default ke jalur Plugin lokal.
• Stable/Beta: memasang Plugin resmi @openclaw/whatsapp dari ClawHub terlebih dahulu, dengan npm sebagai fallback.
• Runtime WhatsApp didistribusikan di luar paket npm inti OpenClaw agar dependensi runtime khusus WhatsApp tetap berada bersama Plugin eksternal.

openclaw plugins install clawhub:@openclaw/whatsapp

​

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>

​

Panggil pemohon saat ini dengan MeowCaller (eksperimental)

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -p "$HOME/.local/bin"
go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"
mkdir -p "$state_dir"
chmod 700 "$state_dir"
meowcaller pair --store "$state_dir/wa-voip.db"

• hanya panggilan audio keluar satu-ke-satu
• tanpa nomor tujuan arbitrer
• tanpa auth bersama dengan koneksi chat
• tanpa panggilan ke diri sendiri dari mode nomor pribadi/chat mandiri
• audio tersintesis dibatasi hingga 60 detik
• tanpa tanda terima keterdengaran di sisi handset selain penyelesaian jawab/pemutaran/tutup dari MeowCaller
• OpenClaw menghentikan proses pendamping setelah jendela terbatas 115-175 detik, termasuk fase koneksi, jawab, pemutaran, dan penghentian MeowCaller

​

Pola deployment

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

​

Model runtime

• Gateway memiliki soket WhatsApp dan loop koneksi ulang.
• Watchdog koneksi 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 hening aplikasi yang lebih panjang tetap memaksa koneksi ulang jika frame transport terus masuk tetapi tidak ada pesan aplikasi yang ditangani selama jendela watchdog; setelah koneksi ulang sementara untuk sesi yang baru-baru ini aktif, pemeriksaan hening aplikasi tersebut menggunakan timeout pesan normal untuk jendela pemulihan pertama.
• Timing soket Baileys eksplisit di bawah web.whatsapp.*: keepAliveIntervalMs mengontrol ping aplikasi WhatsApp Web, connectTimeoutMs mengontrol timeout handshake pembukaan, dan defaultQueryTimeoutMs mengontrol tunggu kueri Baileys plus batas operasi kirim/presence keluar lokal dan tanda terima baca masuk OpenClaw.
• Pengiriman keluar memerlukan listener WhatsApp aktif untuk akun target.
• Pengiriman grup melampirkan metadata mention native untuk token @+<digits> dan @<digits> dalam teks dan caption media ketika token cocok dengan metadata peserta WhatsApp saat ini, termasuk grup berbasis LID.
• Chat status dan broadcast diabaikan (@status, @broadcast).
• Watchdog koneksi ulang mengikuti aktivitas transport WhatsApp Web, bukan hanya volume pesan aplikasi masuk: sesi perangkat tertaut yang sepi tetap aktif selama frame transport berlanjut, tetapi stall transport memaksa koneksi ulang jauh sebelum jalur pemutusan jarak jauh yang lebih akhir.
• 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 @newsletter native. Pengiriman newsletter keluar menggunakan metadata sesi channel (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 utamakan konfigurasi proxy tingkat host daripada pengaturan proxy WhatsApp khusus channel.
• Ketika messages.removeAckAfterReply diaktifkan, OpenClaw menghapus reaksi ack WhatsApp setelah balasan terlihat terkirim.

​

Prompt persetujuan

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session",
    },
    plugin: {
      enabled: true,
      mode: "targets",
      targets: [{ channel: "whatsapp", to: "+15551234567" }],
    },
  },
}

​

Hook Plugin dan privasi

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

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

​

Kontrol akses dan aktivasi

​

Binding ACP yang dikonfigurasi

{
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "direct", id: "+15555550123" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "group", id: "120363424282127706@g.us" },
      },
    },
  ],
}

• Chat langsung cocok dengan nomor E.164 seperti +15555550123.
• Grup cocok dengan JID grup WhatsApp seperti 120363424282127706@g.us.
• Allowlist grup, kebijakan pengirim, dan gerbang mention atau aktivasi berjalan sebelum OpenClaw memastikan sesi ACP yang dikonfigurasi ada.
• Binding ACP terkonfigurasi yang cocok memiliki rute tersebut. Grup broadcast WhatsApp tidak menyebarkan giliran itu ke sesi WhatsApp biasa.

​

Perilaku nomor pribadi dan chat mandiri

• lewati tanda terima baca untuk giliran chat mandiri
• abaikan perilaku pemicu otomatis mention-JID yang jika tidak akan melakukan ping ke diri sendiri
• jika messages.responsePrefix tidak ditetapkan, balasan chat mandiri 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

​

Pengutipan balasan

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

​

Tingkat reaksi

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

​

Reaksi acknowledgment

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

• dikirim segera setelah pesan masuk diterima (sebelum balasan)
• jika ackReaction ada tanpa emoji, WhatsApp menggunakan emoji identitas agen yang dirutekan, dengan fallback ke ”👀”; hilangkan ackReaction atau atur emoji: "" agar tidak mengirim reaksi ack
• kegagalan dicatat dalam log tetapi tidak memblokir pengiriman balasan normal
• mode grup mentions bereaksi pada giliran yang dipicu oleh mention; aktivasi grup always bertindak sebagai bypass untuk pemeriksaan ini
• WhatsApp menggunakan channels.whatsapp.ackReaction (messages.ackReaction lama tidak digunakan di sini)

​

Reaksi status siklus hidup

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        concierge: "💁",
      },
    },
  },
}

• channels.whatsapp.ackReaction tetap mengontrol apakah reaksi status memenuhi syarat untuk pesan langsung dan grup.
• Reaksi status antre menggunakan emoji ack efektif yang sama seperti reaksi ack biasa.
• WhatsApp memiliki satu slot reaksi bot per pesan, sehingga pembaruan siklus hidup mengganti reaksi saat ini di tempat.
• messages.removeAckAfterReply: true menghapus reaksi status akhir setelah masa tahan selesai/galat yang dikonfigurasi.
• Kategori emoji tool mencakup tool, coding, web, deploy, build, dan concierge.

​

Multi-akun dan kredensial

​

Tool, tindakan, dan penulisan konfigurasi

• Dukungan tool agen mencakup tindakan reaksi WhatsApp (react).
• Gate tindakan:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Penulisan konfigurasi yang dimulai oleh 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 channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

Prompt sistem

1. Prompt sistem khusus grup (groups["<groupId>"].systemPrompt): digunakan ketika entri grup spesifik ada di peta 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 ketika entri grup spesifik sepenuhnya tidak ada dari peta, atau ketika entri itu ada tetapi tidak mendefinisikan kunci systemPrompt.

1. Prompt sistem khusus langsung (direct["<peerId>"].systemPrompt): digunakan ketika entri peer spesifik ada di peta dan kunci systemPrompt-nya didefinisikan. Jika systemPrompt adalah string kosong (""), wildcard ditekan dan tidak ada prompt sistem yang diterapkan.
2. Prompt sistem wildcard langsung (direct["*"].systemPrompt): digunakan ketika entri peer spesifik sepenuhnya tidak ada dari peta, atau ketika entri itu ada tetapi tidak mendefinisikan kunci systemPrompt.

• channels.whatsapp.groups adalah peta konfigurasi per grup sekaligus allowlist grup tingkat chat. Pada scope root atau akun, groups["*"] berarti “semua grup diterima” untuk scope tersebut.
• Hanya tambahkan wildcard grup systemPrompt ketika Anda sudah ingin scope tersebut menerima semua grup. Jika Anda masih ingin hanya kumpulan tetap ID grup yang memenuhi syarat, jangan gunakan groups["*"] untuk default prompt. Sebagai gantinya, ulangi prompt pada setiap entri grup yang secara eksplisit ada di allowlist.
• 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 dikontrol 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 langsung default setelah DM sudah diterima oleh dmPolicy ditambah allowFrom atau aturan pairing-store.

{
  channels: {
    whatsapp: {
      groups: {
        // Gunakan hanya jika semua grup harus diizinkan pada cakupan root.
        // Berlaku untuk semua akun yang tidak mendefinisikan peta grupnya sendiri.
        "*": { systemPrompt: "Prompt default untuk semua grup." },
      },
      direct: {
        // Berlaku untuk semua akun yang tidak mendefinisikan peta direct-nya sendiri.
        "*": { systemPrompt: "Prompt default untuk semua chat langsung." },
      },
      accounts: {
        work: {
          groups: {
            // Akun ini mendefinisikan grupnya sendiri, sehingga grup root
            // diganti sepenuhnya. Untuk mempertahankan wildcard, definisikan "*" secara eksplisit di sini juga.
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Fokus pada manajemen proyek.",
            },
            // Gunakan hanya jika semua grup harus diizinkan di akun ini.
            "*": { systemPrompt: "Prompt default untuk grup kerja." },
          },
          direct: {
            // Akun ini mendefinisikan peta direct-nya sendiri, sehingga entri direct root
            // diganti sepenuhnya. Untuk mempertahankan wildcard, definisikan "*" secara eksplisit di sini juga.
            "+15551234567": { systemPrompt: "Prompt untuk chat langsung kerja tertentu." },
            "*": { systemPrompt: "Prompt default untuk chat langsung kerja." },
          },
        },
      },
    },
  },
}

​

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, penimpaan 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

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