diff --git a/container/skills/whatsapp-formatting/SKILL.md b/container/skills/whatsapp-formatting/SKILL.md new file mode 100644 index 000000000..1dabcb344 --- /dev/null +++ b/container/skills/whatsapp-formatting/SKILL.md @@ -0,0 +1,61 @@ +--- +name: whatsapp-formatting +description: Format messages for WhatsApp, including mentions that render as real WhatsApp tags. Use when responding in a WhatsApp conversation (platform_id / chatJid ends with @s.whatsapp.net or @g.us). +--- + +# 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 `chatJid` matching 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 `@` (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` / inbound `content.sender` to 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 `@` — 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.net` in 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. diff --git a/container/skills/whatsapp-formatting/instructions.md b/container/skills/whatsapp-formatting/instructions.md new file mode 100644 index 000000000..0461e0e97 --- /dev/null +++ b/container/skills/whatsapp-formatting/instructions.md @@ -0,0 +1,19 @@ +## WhatsApp mentions — always use phone digits + +When you are replying in a WhatsApp conversation (the inbound message's `chatJid` ends with `@s.whatsapp.net` for a DM or `@g.us` for a group), and you want to tag a person so their name appears **bold and clickable** with a push notification, write `@` followed by their phone-number digits — never the display name. + +**The sender's phone JID is in your inbound message metadata** at `content.sender` (e.g. `15551234567@s.whatsapp.net`). The part before the `@` is exactly what you put after `@` when tagging them. + +| You write | What recipients see | +|-----------|---------------------| +| `@Adam, can you...` | Plain text. No tag, no notification. | +| `@15551234567, can you...` | Bold/blue **@Adam** (whatever name they're saved as), notification fires. | +| `@+15551234567 ...` | Same as above — the adapter strips the `+` automatically. | + +The host adapter scans your outbound text for `@<5–15 digits>` (with optional leading `+`) and tells WhatsApp to render those as real mention tags. If the digits aren't in the text, the tag doesn't render — no exceptions. + +### In groups + +Tag the person you're addressing using their JID from inbound metadata (look at the most recent message from them). Don't guess — pushNames collide and aren't reliable. + +If you don't know someone's JID, refer to them by name in plain prose. Do not write `@` hoping it works.