Messaging

Messaging Commands

The core messaging commands: send, chats, messages, tts, and media.

`omni send`

Send a message to any recipient. Supports text, media, voice notes, reactions, stickers, contacts, locations, polls, embeds, presence indicators, and message forwarding.

1omni send [options]

Common Options

Option	Description
`--instance <id>`	Instance ID (defaults to configured instance)
`--to <recipient>`	Recipient: WhatsApp JID, phone number, or Omni chat/person UUID

Text Messages

12omni send --to +5511999 --text "Hello!"
omni send --to +5511999 --text "Reply" --reply-to <msg-id>

Media Messages

12omni send --to +5511999 --media ./photo.jpg --caption "Check this"
omni send --to +5511999 --media ./audio.mp3 --voice  # Send as voice note

TTS Voice Notes

Convert text to speech and send as a voice note:

12omni send --to +5511999 --tts "Hello from AI!"
omni send --to +5511999 --tts "Custom voice" --voice-id <eleven-labs-id>

Reactions

1omni send --to +5511999 --reaction "👍" --message <msg-id>

Stickers

1omni send --to +5511999 --sticker <url-or-base64>

Contacts

1omni send --to +5511999 --contact --name "John" --phone +5511888 --email john@example.com

Location

1omni send --to +5511999 --location --lat -23.5505 --lng -46.6333 --address "São Paulo"

Polls (Discord)

1omni send --to +5511999 --poll "Lunch?" --options "Pizza,Sushi,Tacos" --multi-select --duration 24

Embeds (Discord)

1omni send --to +5511999 --embed --title "Alert" --description "Server is up" --color "#00ff00"

Presence Indicators

123omni send --to +5511999 --presence composing   # Show "typing..."
omni send --to +5511999 --presence recording   # Show "recording audio..."
omni send --to +5511999 --presence paused      # Clear presence

Message Forwarding

1omni send --to +5511999 --forward --message <msg-id> --from-chat <chat-id>

`omni chats`

Manage conversations across all connected channels.

List and Browse

1234omni chats list                        # List all chats
omni chats get <chat-id>               # Get chat details
omni chats messages <chat-id>          # List messages in a chat
omni chats participants <chat-id>      # List chat participants

Chat Actions

1234567891011omni chats create --instance <id> --to <jid>    # Create a chat record
omni chats archive <chat-id>                      # Archive
omni chats unarchive <chat-id>                    # Unarchive
omni chats hide <chat-id>                          # Hide from list
omni chats unhide <chat-id>                        # Unhide
omni chats pin <chat-id>                           # Pin on channel
omni chats unpin <chat-id>                         # Unpin
omni chats mute <chat-id>                          # Mute
omni chats unmute <chat-id>                        # Unmute
omni chats read <chat-id>                          # Mark as read
omni chats disappearing <chat-id> --duration 7d   # Toggle disappearing messages

Chat fields

omni chats list and omni chats get return the canonical chat record. Two fields are worth calling out:

Field	Description
`isGroup`	`true` for group chats, `false` for 1:1. Derived from the channel's external chat ID (e.g. `@g.us` suffix on WhatsApp), so it is always present and consistent across channels. Use this in automation conditions instead of pattern-matching on JID strings.
`personId`	Stable Omni person UUID. On WhatsApp, Omni canonicalises LID and JID identifiers so the same human is one `personId` regardless of which form the channel reports.

12345678# List only group chats
omni chats list --json | jq '.[] | select(.isGroup == true)'

# Filter automation conditions on isGroup instead of JID
omni automations create \
  --trigger message.received \
  --action call_agent \
  --condition '[{"field": "payload.chat.isGroup", "op": "eq", "value": false}]'

Labels

12omni chats label <chat-id> "vip"       # Add label
omni chats unlabel <chat-id> "vip"     # Remove label

Clear an agent session (HTTP)

POST /v2/chats/clear-session rotates the conversation's agent session ID and re-arms it for the next inbound message. Use it from an integration when the operator wants to "reset" the running agent for a chat without disconnecting the channel.

1234curl -X POST https://omni.example.com/v2/chats/clear-session \
  -H "Authorization: Bearer $OMNI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId": "0c6f8...","chatId": "5511..."}'

Body field	Required	Description
`instanceId`	yes	UUID of the channel instance
`chatId`	yes	External chat ID (e.g. WhatsApp JID)

The endpoint accepts application/json, application/x-www-form-urlencoded, and multipart/form-data. On success it returns { success: true, sessionId, sessionStrategy } and as a side-effect disarms any pending follow-ups and unpauses the agent (mirrors the trash-emoji behaviour from inside the chat).

Clearing a session does not delete chat history — only the agent's conversation handle is rotated.

`omni messages`

Manage individual messages.

12345678omni messages get <msg-id>                     # Get full message details (includes transcriptions)
omni messages search <query>                   # Full-text search across chats
omni messages read <msg-id>                    # Mark as read
omni messages edit <msg-id> --text "Updated"   # Edit a sent message
omni messages delete <msg-id>                  # Delete for everyone (WhatsApp)
omni messages star <msg-id>                    # Star a message
omni messages unstar <msg-id>                  # Unstar
omni messages remove-reaction <msg-id>         # Remove a reaction

`omni tts`

Text-to-speech operations.

1omni tts voices    # List available TTS voices

TTS is also available via omni send --tts.

`omni media`

Browse and download media items.

12omni media list                    # List media with transcriptions/descriptions
omni media download --id <id>     # Download a media item

Verb commands

Verb commands are shorthand for common multimodal messaging operations. Each verb infers --instance and --chat from context (active chat or automation trigger), or you can override them explicitly.

The imagine, film, see, speak, and listen verbs require provider credentials configured on your Omni server (Gemini, ElevenLabs, or Groq).

`omni say`

Send a text message to the open chat.

1omni say <text> [options]

Option	Description
`--reply [message-id]`	Quote-reply to trigger message or a specific message
`--instance <id>`	Override instance
`--chat <id>`	Override chat

12omni say "Hello from the CLI"
omni say "Got it!" --reply

`omni react`

React to a message with an emoji.

1omni react <emoji> [options]

Option	Description
`--message <id>`	Message ID to react to (default: trigger message from context)
`--instance <id>`	Override instance
`--chat <id>`	Override chat

12omni react "👍"
omni react "🎉" --message BAE5A47F3F373B35

`omni speak`

Synthesize text to speech and send as a voice note.

1omni speak <text> [options]

Option	Description
`--provider <name>`	TTS provider: `gemini`, `elevenlabs` (default: server config)
`--voice <name>`	Voice identifier (e.g., `Kore` for Gemini)
`--style <prompt>`	Style prompt prepended to text (Gemini only)
`--language <code>`	BCP-47 language code (e.g., `en-US`, `pt-BR`)
`--speed <factor>`	Speaking speed multiplier `0.5`–`2.0`
`--format <fmt>`	Audio format: `mp3`, `ogg`, `opus`, `wav`, `pcm`, `flac`, `aac` (default: `ogg`)
`--output <path>`	Save audio to file instead of sending

123omni speak "The deployment is complete"
omni speak "Bom dia!" --voice Kore --language pt-BR
omni speak "Save this locally" --output greeting.ogg

`omni listen`

Transcribe an audio file to text.

1omni listen <file> [options]

Option	Description
`--provider <name>`	STT provider: `gemini`, `groq` (default: server config)
`--language <code>`	BCP-47 language hint (e.g., `en`, `pt-BR`)
`--timestamps`	Include per-segment timestamps
`--format <fmt>`	Output format: `text`, `json` (default: `text`)
`--model <name>`	Model override (provider-specific)
`--reply [message-id]`	Send transcript as a quote-reply

123omni listen voice-note.ogg
omni listen meeting.mp3 --timestamps --format json
omni listen audio.ogg --reply --language pt-BR

`omni imagine`

Generate an image from a text prompt using Gemini Nano Banana and send it to the active chat, or save it locally with --output.

1omni imagine <prompt> [options]

Prompts are free-form text describing the desired image. Longer, descriptive prompts that specify subject, style, lighting, and composition tend to produce better results (e.g. "A neon-lit cyberpunk street at night, cinematic wide shot, rain-slick pavement"). By default the generated image is delivered to the current chat; pass --output <path> to write it to disk instead (for --count > 1, -N is appended to the filename).

Option	Description
`--aspect-ratio <ratio>`	Aspect ratio: `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `3:2`, `2:3`
`--size <size>`	Image size preset: `1K`, `2K`, `4K` (not all models support all sizes)
`--model <name>`	Model alias (`nano-banana-2`, `nano-banana-pro`) or raw Gemini model ID
`--provider <name>`	Provider override (default: server `imagegen.provider` config)
`--count <n>`	Number of images to generate (`1`–`4`, default: `1`)
`--output <path>`	Save locally instead of sending (appends `-N` when `--count > 1`)
`--reply [message-id]`	Quote-reply to the trigger message or a specific message

1234omni imagine "A sunset over a cyberpunk city"
omni imagine "Logo for an AI company" --aspect-ratio 1:1 --count 4
omni imagine "Architecture diagram" --output diagram.png
omni imagine "Portrait of a fox in a meadow" --model nano-banana-pro --size 2K

`omni film`

Generate a video from a text prompt using Gemini Veo 3.1.

1omni film <prompt> [options]

Option	Description
`--duration <seconds>`	Clip duration in seconds
`--resolution <res>`	Resolution hint: `720p` or `1080p`
`--aspect-ratio <ratio>`	Aspect ratio: `16:9` or `9:16` (default: `16:9`)
`--seed <number>`	RNG seed for reproducible output
`--no-audio`	Disable audio generation
`-o, --output <path>`	Save video to file locally (does not send)
`--provider <name>`	Video generation provider (default: `gemini`)
`--reply [message-id]`	Quote-reply to a message

1234omni film "A drone shot flying over a tropical forest"
omni film "Product demo animation" --resolution 1080p --output demo.mp4
omni film "Vertical reel of city lights at night" --aspect-ratio 9:16
omni film "Silent ambient loop of rain on leaves" --no-audio

`omni see`

Describe an image or video using Gemini Vision.

1omni see <file> [prompt] [options]

Option	Description
`--provider <name>`	Vision provider: `gemini` (default: server config)
`--language <code>`	Response language (e.g., `en`, `pt-BR`)
`--max-tokens <n>`	Maximum output tokens (`1`–`8192`)
`--reply [message-id]`	Send description as a quote-reply

123omni see photo.jpg
omni see screenshot.png "What error is shown?"
omni see receipt.jpg "Extract the total amount" --reply

Session verbs

These verbs operate on the active conversation — the chat you previously selected with omni use <instance> and omni open <chat>. They infer --instance and --chat from that context, so they're convenient inside an automation handler or an interactive session.

Verb	Description
`omni use <instance>`	Set the active instance for verb commands. Accepts an instance name, ID, or unique prefix.
`omni open`	Open a chat in the active instance (sets the active chat for subsequent verbs).
`omni close`	Close the open chat without sending anything (clears active-chat context).
`omni done`	Mark the current verb interaction as complete (used by automation handlers to signal end of a turn).
`omni where`	Show the current conversation context — instance, chat, and last message. Handy for "what am I about to send to?" sanity checks.
`omni history [chat]`	Show recent message history for the active chat (or a chat passed explicitly).

Session verbs are most useful inside an omni automations call_agent handler — the active context is set automatically by the trigger, so the agent can run omni react, omni say, and omni done without needing to know the chat ID.

Run omni <verb> --help for the full flag table.

Ask AI about this page