Skip to content

docs(omni-send): drop @s.whatsapp.net JID suffix from --to examples #612

@automagik-genie

Description

@automagik-genie

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

  1. plugins/omni/commands/send.md — line 20 example uses 5511999999999@s.whatsapp.net. Drop the suffix.
  2. 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.
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions