whatsapp-web-js

WhatsApp Web.js

Puppeteer を介して Chromium ブラウザーインスタンスを操作し、WhatsApp Web を自動化するライブラリ、whatsapp-web.js に関する専門的なガイダンスを提供します。

クイックスタート

認証方式を設定してクライアントを初期化し、イベントをリッスンします。

const { Client, LocalAuth } = require('whatsapp-web.js');

const client = new Client({
    authStrategy: new LocalAuth(),
    puppeteer: { headless: true }
});

client.on('qr', (qr) => console.log('Scan QR:', qr));
client.on('ready', () => console.log('Client ready'));
client.on('message', async (msg) => {
    if (msg.body === 'ping') await msg.reply('pong');
});

client.initialize();  // Non-blocking - listen for 'ready' event

要件：Node.js >= 18.0.0、puppeteer（必須）、ffmpeg（スタンプを使用する場合は任意）。

ID 形式の規則

チャット操作では、常に正しい ID 形式を使用してください。

• 個人チャット：<country_code><phone>@c.us（例：[email protected]）
• グループ：<id>@g.us（例：[email protected]）
• チャンネル：<id>@newsletter
• ステータスの一斉送信：status@broadcast

電話番号には + と先頭のゼロを含めません。例：米国の +1 (234) 567-8901 は [email protected] になります。

認証方式

デプロイモデルに応じて選択してください。

// No persistence - QR scan every restart
new NoAuth()

// Local filesystem - recommended for single-instance bots
new LocalAuth({ clientId: 'bot1' })

// Remote store - for cloud/multi-instance deployments
new RemoteAuth({ store: myStore, clientId: 'bot1', backupSyncIntervalMs: 60000 })

ペアリングコード認証

電話番号でペアリングして、QR コードのスキャンを省略します。

const client = new Client({
    authStrategy: new LocalAuth(),
    pairWithPhoneNumber: {
        phoneNumber: '5511999999999',  // country code + number, no symbols
        showNotification: true,
        intervalMs: 180000
    }
});
client.on('code', (code) => console.log('Pairing code:', code));

基本パターン

メッセージの送信

// Text message
await client.sendMessage('[email protected]', 'Hello!');

// Reply to received message
await msg.reply('Got it!');

// With mentions
await client.sendMessage(chatId, 'Hi @5511999999999', {
    mentions: ['[email protected]']
});

// Quote specific message
await client.sendMessage(chatId, 'Replying to this', {
    quotedMessageId: msg.id._serialized
});

メディアの処理

const { MessageMedia } = require('whatsapp-web.js');

// From file
const media = MessageMedia.fromFilePath('/path/to/image.png');
await client.sendMessage(chatId, media, { caption: 'Check this out' });

// From URL
const media = await MessageMedia.fromUrl('https://example.com/image.png');
await client.sendMessage(chatId, media);

// Download received media
if (msg.hasMedia) {
    const media = await msg.downloadMedia();
    // Access: media.mimetype, media.data (base64), media.filename
}

メディア送信のバリエーション

特定のオプションを指定して、メディアの送信方法を制御します。

// As sticker (requires ffmpeg)
await client.sendMessage(chatId, media, { sendMediaAsSticker: true });

// As voice note
await client.sendMessage(chatId, audio, { sendAudioAsVoice: true });

// As HD quality
await client.sendMessage(chatId, media, { sendMediaAsHd: true });

// As view-once
await client.sendMessage(chatId, media, { isViewOnce: true });

// As document
await client.sendMessage(chatId, media, { sendMediaAsDocument: true });

投票、リアクション、位置情報

const { Poll, Location } = require('whatsapp-web.js');

// Poll (single choice)
await client.sendMessage(chatId, new Poll('Question?', ['A', 'B']));

// Poll (multiple choice)
await client.sendMessage(chatId, new Poll('Pick', ['A', 'B', 'C'], 
    { allowMultipleAnswers: true }));

// React to message
await msg.react('👍');   // add reaction
await msg.react('');      // remove reaction

// Send location
await client.sendMessage(chatId, 
    new Location(37.422, -122.084, { name: 'Googleplex' }));

メッセージ操作

// Edit sent message
const sent = await client.sendMessage(chatId, 'Original');
await sent.edit('Edited text');

// Delete message
await sent.delete(true);  // true = delete for everyone

// Pin message
await msg.pin(86400);     // Pin for 24h (86400|604800|2592000 seconds)
await msg.unpin();

重要な注意点

• client.initialize() は非ブロッキングです — クライアントを使用する前に、必ず ready イベントをリッスンしてください
• message イベントは受信時にのみ発生します — 送信メッセージも取得するには message_create を使用してください
• メッセージ ID には ._serialized が必要です — 文字列表現には msg.id._serialized を使用してください
• グループ管理者の操作 — setSubject、removeParticipants などを実行するには、ボットが管理者である必要があります
• レート制限 — 一時的なブロックを避けるため、一括送信の間に遅延を入れてください
• fetchMessages() はキャッシュから読み込みます — 履歴全体を同期するには chat.syncHistory() を呼び出してください
• スタンプの変換には ffmpeg が必要です — スタンプを使用するには、システムの PATH にインストールしてください
• メモリに関する考慮事項 — 実際の Chromium インスタンスを実行するため、複数クライアントのセットアップを計画してください
• ステータスメッセージ — chatId として status@broadcast に送信してください

主なイベント

ボットのロジックに不可欠なイベント：

イベント	用途
ready	クライアントの使用準備が完了
message	受信メッセージのみ
message_create	すべてのメッセージ（自分が送信したものを含む）
message_ack	配信状況を追跡（0=保留中、1=サーバー、2=デバイス、3=既読、4=再生済み）
qr	認証用 QR コード
authenticated	認証成功
disconnected	再接続処理

参考資料

特定の機能を実装する際は、以下の詳細なリファレンスを参照してください。

• detailed-guide.md — WhatsApp Web.js の機能を実装する際は、必ずお読みください。カテゴリ別に整理された包括的な API リファレンスで、メッセージ、メディア、チャット、グループ、チャンネル、連絡先、イベントが含まれます。すべてのメソッドシグネチャ、オプション、戻り値の型、コード例を掲載しています。慣れていない操作や、予期しない動作のデバッグを行う場合は、ここから確認してください。