Rendered HTML content
'\n})\n```\n\n`sendHtmlMessage` uses an experimental HTML primitive. Do not pass untrusted user input into HTML without sanitizing it.\n\nThe experimental rich menu helper accepts a header, body buttons, cards, and footer:\n\n```js\nawait sock.richMenu(jid, {\n header: { title: 'Deploy Suite' },\n body: {\n title: 'Choose an action',\n buttons: [\n { id: 'deploy', text: 'Deploy' },\n { id: 'logs', text: 'View logs' }\n ]\n },\n footer: { text: 'Example menu' }\n})\n```\n\nAlways validate button IDs on the server. Never treat a user-controlled button ID as an authorization grant.\n\n## Carousels and rich button grids\n\nUse `sendRichButtonGrid` for media cards with native-flow buttons. A carousel needs at least one valid image, video, or product header per card. The helper accepts either `buttons` or `nativeFlow`.\n\n```js\nawait sock.sendRichButtonGrid(jid, {\n text: 'Choose an option',\n footer: 'Select one',\n cards: [\n {\n image: { url: './first.jpg' },\n title: 'First card',\n caption: 'First card description',\n buttons: [\n { id: 'first', text: 'Select first' }\n ]\n },\n {\n image: { url: './second.jpg' },\n title: 'Second card',\n caption: 'Second card description',\n buttons: [\n { id: 'second', text: 'Select second' }\n ]\n }\n ]\n})\n```\n\nSupported button properties include `id`, `text`, `url`, `call`, and `copy`. Carousel cards must have valid media headers. A card containing only text is not a valid carousel card.\n\nFor a single native-flow message:\n\n```js\nawait sock.sendMessage(jid, {\n text: 'Open the site',\n nativeFlow: [\n { url: 'https://example.com', text: 'Open' }\n ]\n})\n```\n\n## Media albums\n\nAlbums are sent as a parent album message followed by associated image or video child messages. Provide at least two media items:\n\n```js\nawait sock.sendMessage(jid, {\n album: [\n {\n image: { url: './image-1.jpg' },\n caption: 'First image'\n },\n {\n image: { url: './image-2.jpg' },\n caption: 'Second image'\n }\n ]\n})\n```\n\nAlbum children are required to be actual `imageMessage` or `videoMessage` payloads. A `botForwardedMessage` or `richResponseMessage` cannot be nested as an album child. If rich text or a rich-response envelope is needed, send it as a separate message before or after the album.\n\n## Experimental bot metadata\n\nThe following methods attach newer `WAProto` bot metadata fields through `messageContextInfo.botMetadata`. They are experimental and may have no visible effect unless the receiving client and server support the corresponding first-party feature.\n\n### Diagnostics metadata\n\n```js\nawait sock.sendBotDiagnostics(jid, {\n text: 'Diagnostics test',\n botBackend: 1, // 0 = AAPI, 1 = CLIPPY\n toolsUsed: ['web_search', 'image_search'],\n isThinking: true\n})\n```\n\n### Command metadata\n\n```js\nawait sock.sendBotCommand(jid, {\n text: 'Command metadata test',\n commandName: 'summarize',\n commandDescription: 'Summarize the current conversation',\n commandPrompt: 'Summarize the current conversation in five bullets'\n})\n```\n\n### Resolved tool-call metadata\n\n```js\nawait sock.sendBotToolResult(jid, {\n text: 'Tool result test',\n toolCallId: `tool-${Date.now()}`,\n resolutionData: {\n status: 'success',\n result: { value: 'Completed' }\n }\n})\n```\n\nYou may provide a pre-serialized result instead:\n\n```js\nawait sock.sendBotToolResult(jid, {\n text: 'Serialized result',\n toolCallId: 'tool-123',\n resolutionDataSerialized: JSON.stringify({\n status: 'success',\n value: 'Completed'\n })\n})\n```\n\nThese methods do not fabricate Meta's verification certificates or signatures. They should not be treated as a way to impersonate a first-party Meta AI response.\n\n## Status updates\n\nUse `backgroundColor` rather than `backgroundArgb` in the high-level API:\n\n```js\nawait sock.sendStatus({\n text: 'Service status: online',\n backgroundColor: 0xff102a43,\n font: 2\n}, {\n statusJidList: ['15551234567@s.whatsapp.net']\n})\n```\n\nAlternatively, send directly to `status@broadcast` when using the raw status protocol supported by the installed version.\n\n## Groups\n\n```js\nconst metadata = await sock.groupMetadata(groupJid)\nawait sock.groupParticipantsUpdate(groupJid, [userJid], 'add')\nawait sock.groupParticipantsUpdate(groupJid, [userJid], 'remove')\nawait sock.groupSettingUpdate(groupJid, 'announcement')\n```\n\nGroup administration requires the corresponding privileges. Handle permission failures and disconnected sessions.\n\n### Group member labels\n\n`updateMemberLabel` sets the connected account's own custom member label in a\ngroup. The first argument must be the **group JID** (`123456789-123456@g.us`),\nnot the member's individual JID:\n\n```js\nawait sock.updateMemberLabel(groupJid, 'Developer')\n```\n\nTo remove the label, pass an empty string:\n\n```js\nawait sock.updateMemberLabel(groupJid, '')\n```\n\nLabels are limited to 30 characters by the protocol. This is not an admin\noperation for assigning labels to arbitrary participants; WhatsApp associates\nthe label with the account that sends the protocol message.\n\n## WhatsApp Flows and web views\n\n```js\nawait sock.sendWhatsAppFlow(jid, {\n flowId: '1234567890',\n flowToken: 'example-token',\n cta: 'Open flow',\n text: 'Complete this form'\n})\n\nawait sock.sendRichWebview(jid, {\n url: 'https://example.com/app',\n text: 'Open the app',\n buttonText: 'Open'\n})\n```\n\nThe flow ID, token, and hosted URL must be valid for the target business configuration.\n\n## Message options\n\n```js\nawait sock.sendMessage(jid, {\n text: 'Disappearing message',\n ephemeralExpiration: 86400\n})\n\nawait sock.sendMessage(jid, {\n text: 'Updated text',\n edit: message.key\n})\n\nawait sock.sendMessage(jid, {\n delete: message.key\n})\n```\n\nRaw protocol fields are version-dependent. Unsupported fields may be ignored or rejected by WhatsApp.\n\n## Error handling and reconnection\n\nConnections may close because of logout, network interruption, protocol updates, or server-side session invalidation. Avoid starting multiple concurrent connection loops.\n\n```js\nsock.ev.on('connection.update', ({ connection, lastDisconnect }) => {\n if (connection !== 'close') return\n\n const status = new Boom(lastDisconnect?.error)?.output?.statusCode\n if (status === DisconnectReason.loggedOut) {\n console.error('Logged out; remove the old session and pair again.')\n return\n }\n\n console.log('Connection interrupted; reconnect with backoff.')\n})\n```\n\n## Development\n\n```bash\nnpm install\nnpm test\n```\n\nBefore publishing, verify generated protobuf files, package contents, version metadata, and that no authentication state or environment files are included.\n\n## License\n\nReview the included license before distributing applications built with `plogme`. Keep required notices with redistributed source and binaries.\n\n## Support\n\nFor implementation questions, include the Node.js version, `plogme` version, operating system, relevant error text, and a minimal reproducible example. Never include authentication state or private account data in an issue.\n\n\n## Ported WhatsApp Web protocol features\n\nThe bundled WAProto schema is updated to WhatsApp Web version `2.3000.1047412487`, with the generated runtime, TypeScript declarations, and connection version updated together. Selected support includes newsletter follower-invite base/V2 fields, ACP2 receive-state extraction, animated wallpaper encoding, and nested audio in sticker messages. These remain experimental and client-dependent.\n\n### Animated wallpaper\n\n```js\nawait sock.sendMessage(jid, {\n chatTheme: {\n animatedWallpaper: { id: 'wallpaper-id', dimLevel: 0.25 }\n }\n})\n```\n\n### Sticker with audio\n\n```js\nawait sock.sendMessage(jid, {\n sticker: { url: './sticker.webp' },\n stickerAudio: { url: './sound.ogg' }\n})\n```\n\n### Newsletter follower invites\n\n```js\nawait sock.sendMessage(jid, {\n newsletterFollowerInvite: {\n newsletterJid: '123456789@newsletter',\n newsletterName: 'My newsletter',\n caption: 'Follow this channel'\n }\n})\n\nawait sock.sendMessage(jid, {\n newsletterFollowerInviteMessageV2: {\n newsletterJid: '123456789@newsletter',\n newsletterName: 'My newsletter',\n caption: 'Follow this channel'\n }\n})\n```\n\n### Device-scoped relay options\n\n`relayMessage` supports `isSecret`, `protected`, and `me` for supported private-chat device fan-out paths. These select recipients and may add `device_fanout`; they are not encryption, access-control, or delivery guarantees and may not behave identically for groups, statuses, retries, or future clients. They are unrelated to the protobuf field `messageContextInfo.messageSecret`.\n\n```js\nawait sock.relayMessage(jid, message, {\n messageId: messageId,\n isSecret: true\n})\n```\n\n### Explicit album wrapper\n\nAlbums remain parent/child wire messages: one album header is relayed first, followed by separately encrypted image/video children associated with the parent key. The receiver must group them visually. The explicit wrapper accepts typed media objects and applies a caption to the first child:\n\n```js\nawait sock.sendAlbumMessage(jid, [\n { type: 'image', data: { url: './one.jpg' } },\n { type: 'image', data: { url: './two.jpg' } }\n], { caption: 'Album caption' })\n```\n\nRich HTML and bot-forwarded messages cannot be album children; send those separately. Album grouping is still dependent on WhatsApp server/client behavior.\n","readmeFilename":"README.md"}