Summary
The omni send --to flag accepts a plain phone number (e.g. 5534996835777) for WhatsApp 1:1 chats. The CLI/API resolves the channel automatically. However, the documentation and quickstart examples currently push users toward the full JID form (5534996835777@s.whatsapp.net), which is unnecessary noise and confuses agents/operators.
The JID suffix is only required for groups (@g.us), LIDs (@lid), or non-WhatsApp platforms that demand a fully-qualified channel ID.
Reproduction
# Both work, but the second is what we should be teaching:
omni send --instance <id> --to 5534996835777@s.whatsapp.net --text "hi"
omni send --instance <id> --to 5534996835777 --text "hi"
Real send confirmation (status=sent on the plain-phone form):
"to": "5534996835777"
"status": "sent"
Files to fix
plugins/omni/commands/send.md — line 20 example uses 5511999999999@s.whatsapp.net. Drop the suffix.
plugins/omni/skills/omni-send/SKILL.md — Notes section (--to accepts phone/JID or Omni UUIDs) is too vague. Make plain phone the explicit default for WhatsApp 1:1, and call out JID only as the escape hatch for groups/LIDs/other platforms.
plugins/omni/skills/omni-send/SKILL.md — contact-resolution workflow currently teaches JID=$(... platformUserId); should resolve phone instead and only fall back to platformUserId for groups/LIDs.
Suggested fix (skill Notes section)
Replace:
--to accepts phone/JID or Omni UUIDs (chat/person).
with:
--to accepts a plain phone number (preferred for WhatsApp 1:1, e.g. 5511999999999), a full JID (only needed for groups @g.us, LIDs @lid, or other platforms that require it), or an Omni UUID (chat/person). Drop the @s.whatsapp.net suffix in normal direct messages — the CLI resolves the channel automatically.
Why this matters
- Cleaner agent-generated commands (LLMs copy patterns from skill docs).
- Removes a foot-gun where users format the phone wrong inside the JID and silently fail.
- Matches how the CLI actually behaves today, no behavior change required.
Out of scope
No code change in the CLI/API. Documentation only.
Summary
The
omni send --toflag accepts a plain phone number (e.g.5534996835777) for WhatsApp 1:1 chats. The CLI/API resolves the channel automatically. However, the documentation and quickstart examples currently push users toward the full JID form (5534996835777@s.whatsapp.net), which is unnecessary noise and confuses agents/operators.The JID suffix is only required for groups (
@g.us), LIDs (@lid), or non-WhatsApp platforms that demand a fully-qualified channel ID.Reproduction
Real send confirmation (status=sent on the plain-phone form):
Files to fix
plugins/omni/commands/send.md— line 20 example uses5511999999999@s.whatsapp.net. Drop the suffix.plugins/omni/skills/omni-send/SKILL.md— Notes section (--to accepts phone/JID or Omni UUIDs) is too vague. Make plain phone the explicit default for WhatsApp 1:1, and call out JID only as the escape hatch for groups/LIDs/other platforms.plugins/omni/skills/omni-send/SKILL.md— contact-resolution workflow currently teachesJID=$(... platformUserId); should resolvephoneinstead and only fall back toplatformUserIdfor groups/LIDs.Suggested fix (skill Notes section)
Replace:
with:
Why this matters
Out of scope
No code change in the CLI/API. Documentation only.