WhatsApp Message Formatting
WhatsApp uses its own lightweight markup and a phone-number-based mention syntax. The host's WhatsApp adapter (Baileys) handles markdown conversion automatically, but mentions are only protocol-level mentions if you use the right syntax — otherwise they render as plain text and don't notify the recipient.
How to detect WhatsApp context
You're in a WhatsApp conversation when any of these are true:
- The chat JID / platform id ends with
@s.whatsapp.net(1-on-1 DM) - The chat JID / platform id ends with
@g.us(group) - Your inbound message metadata has
chatJidmatching the above
Mentions — the important part
To tag a user so their name appears bold and clickable in WhatsApp and they get a push notification, write the @ followed by their phone number digits (no +, no spaces, no display name):
@15551234567 can you confirm?The adapter scans your outgoing text for @<digits> (5–15 digits, optional leading + is stripped) and tells WhatsApp to render them as real mention tags.
The sender's phone JID is always in your inbound message metadata. When a user writes to you, inbound content.sender looks like 15551234567@s.whatsapp.net. The part before the @ is exactly what you put after @ when tagging them back.
Wrong vs right
| You write | What recipients see | |-----------|---------------------| | @Adam can you... | Plain text @Adam. No tag, no notification. | | @15551234567 can you... | Bold/blue @Adam (or whatever name they're saved as), notification fires. | | @+15551234567 ... | Same as above — adapter strips the +. |
Picking who to tag
- In a DM, there's no real need to tag the recipient (they already see every message), but tagging still works if you want emphasis.
- In a group, look at the
participants/ inboundcontent.senderto find the JID of the person you mean. Don't guess from display names — pushNames can collide and are not reliable. - If you don't know the JID, just refer to the person by name in plain prose. Don't write
@<name>— it won't tag and it will look like a tag that failed.
Text styles
WhatsApp uses single-character delimiters, not doubled like standard Markdown.
| Style | Syntax | Renders as | |-------|--------|------------| | Bold | bold | bold | | Italic | _italic_ | italic | | Strikethrough | ~strike~ | ~strike~ | | Monospace | ` code | code | | Block monospace | `` `block` ``` | preformatted block |
The adapter converts standard Markdown (bold, [link](url), # heading) to the WhatsApp-native form automatically, so you don't have to think about it — but be aware that single asterisks become italics, not bold.
What not to do
- Don't write
<@U123>(that's Slack),<@!123>(Discord), or any other channel's mention syntax. - Don't paste a full JID like
@15551234567@s.whatsapp.netin the text — only the digits before the JID's@go after your@. - Don't try to tag display names. WhatsApp has no display-name-based mention API.