Add implementation plan for sendMessage raw proto mode (raw: true)

[Copilot]

This PR addresses the request to support raw WhatsApp proto-shaped payloads in sendMessage (for cases like extendedTextMessage.contextInfo.externalAdReply) and to formalize how that mode should behave. It contributes a detailed implementation plan and PR scaffolding for the raw-message method branch.

• Scope

  • Captures the target feature: opt-in raw payload sending via raw: true.
  • Defines the expected integration points in the current message pipeline (AnyMessageContent typing, generateWAMessageContent, generateWAMessageFromContent, and sendMessage relay path).

• Planned implementation breakdown

  • Type-system extension for raw-mode input contract.
  • Raw-path handling in message generation that bypasses helper-field composition.
  • Context/quoted compatibility requirements for raw-built messages.
  • Documentation updates in both main README and examples README.
  • Regression coverage for raw payload fidelity and invalid-shape handling.

• Branch/PR setup

  • Prepared dedicated branch context for raw message method work.
  • Opened PR to track and review the implementation plan before landing runtime changes.

await sock.sendMessage(jid, {
  extendedTextMessage: {
    text: '📃 Built manually from scratch using the raw WhatsApp proto structure',
    contextInfo: {
      externalAdReply: {
        title: '@itsliaaa/baileys',
        thumbnail: fs.readFileSync('./path/to/image.jpg'),
        sourceApp: 'whatsapp',
        showAdAttribution: true,
        mediaType: 1
      }
    }
  },
  raw: true
}, { quoted: message })

---

Summary by cubic

Adds opt-in raw proto mode to sendMessage for advanced WhatsApp messages. Previously only helper-shaped content was accepted; now with raw: true, we accept WAProto.IMessage top-level keys and build a WAProto.Message directly, leaving default behavior unchanged.

• Validates raw payloads: disallows helper fields, requires only valid proto.Message keys, rejects inherited/proto-function keys (e.g., toJSON), and requires at least one top-level key. Proto keys that overlap helper names are allowed.

• Preserves quoting: generateWAMessage merges quoted metadata into raw contextInfo without changing the send pipeline.

• Types: adds RawMessageContent (gated by raw: true) to AnyMessageContent.

• Implementation: new buildRawMessageContent path in generateWAMessageContent using WAProto.Message.fromObject; defines MESSAGE_PROTO_KEYS and a helper-key denylist.

• Docs/tests: README and examples document raw mode; tests cover fidelity, key validation, mixed-field errors, proto-function keys, and quoted behavior.

• Required usage: To send raw payloads, pass raw: true and only proto message keys; do not mix helper fields; payload must be non-empty.

^{Written for commit 18a16a6. Summary will update on new commits.}

[github-actions]

Thanks for opening this pull request and contributing to the project!

The next step is for the maintainers to review your changes. If everything looks good, it will be approved and merged into the main branch.

In the meantime, anyone in the community is encouraged to test this pull request and provide feedback.

✅ How to confirm it works

If you’ve tested this PR, please comment below with:

Tested and working ✅

This helps us speed up the review and merge process.

📦 To test this PR locally:

# NPM
npm install @innovatorssoft/baileys@innovatorssoft/Baileys#copilot/raw-message-method

# Yarn (v2+)
yarn add @innovatorssoft/baileys@innovatorssoft/Baileys#copilot/raw-message-method

# PNPM
pnpm add @innovatorssoft/baileys@innovatorssoft/Baileys#copilot/raw-message-method

If you encounter any issues or have feedback, feel free to comment as well.

[devin-ai-integration]

Devin Review found 2 potential issues.

View 1 additional finding in Devin Review.