> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Messaging

> Send messages, manage chats, search messages, handle media — the core Omni commands.

# 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.

```bash theme={"dark"}
omni 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

```bash theme={"dark"}
omni send --to +5511999 --text "Hello!"
omni send --to +5511999 --text "Reply" --reply-to <msg-id>
```

### Media Messages

```bash theme={"dark"}
omni 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:

```bash theme={"dark"}
omni send --to +5511999 --tts "Hello from AI!"
omni send --to +5511999 --tts "Custom voice" --voice-id <eleven-labs-id>
```

### Reactions

```bash theme={"dark"}
omni send --to +5511999 --reaction "👍" --message <msg-id>
```

### Stickers

```bash theme={"dark"}
omni send --to +5511999 --sticker <url-or-base64>
```

### Contacts

```bash theme={"dark"}
omni send --to +5511999 --contact --name "John" --phone +5511888 --email john@example.com
```

### Location

```bash theme={"dark"}
omni send --to +5511999 --location --lat -23.5505 --lng -46.6333 --address "São Paulo"
```

### Polls (Discord)

```bash theme={"dark"}
omni send --to +5511999 --poll "Lunch?" --options "Pizza,Sushi,Tacos" --multi-select --duration 24
```

### Embeds (Discord)

```bash theme={"dark"}
omni send --to +5511999 --embed --title "Alert" --description "Server is up" --color "#00ff00"
```

### Presence Indicators

```bash theme={"dark"}
omni 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

```bash theme={"dark"}
omni send --to +5511999 --forward --message <msg-id> --from-chat <chat-id>
```

***

## `omni chats`

Manage conversations across all connected channels.

### List and Browse

```bash theme={"dark"}
omni 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

```bash theme={"dark"}
omni 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.                                                                                            |

```bash theme={"dark"}
# 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

```bash theme={"dark"}
omni 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.

```bash theme={"dark"}
curl -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).

<Note>
  Clearing a session does **not** delete chat history — only the agent's conversation handle is rotated.
</Note>

***

## `omni messages`

Manage individual messages.

```bash theme={"dark"}
omni 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.

```bash theme={"dark"}
omni tts voices    # List available TTS voices
```

TTS is also available via `omni send --tts`.

***

## `omni media`

Browse and download media items.

```bash theme={"dark"}
omni 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.

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

### `omni say`

Send a text message to the open chat.

```bash theme={"dark"}
omni 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                                        |

```bash theme={"dark"}
omni say "Hello from the CLI"
omni say "Got it!" --reply
```

### `omni react`

React to a message with an emoji.

```bash theme={"dark"}
omni 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                                                  |

```bash theme={"dark"}
omni react "👍"
omni react "🎉" --message BAE5A47F3F373B35
```

### `omni speak`

Synthesize text to speech and send as a voice note.

```bash theme={"dark"}
omni 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                                            |

```bash theme={"dark"}
omni 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.

```bash theme={"dark"}
omni 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                        |

```bash theme={"dark"}
omni 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`.

```bash theme={"dark"}
omni 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                |

```bash theme={"dark"}
omni 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.

```bash theme={"dark"}
omni 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                         |

```bash theme={"dark"}
omni 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.

```bash theme={"dark"}
omni 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                  |

```bash theme={"dark"}
omni 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).                                                   |

<Note>
  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.
</Note>

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