openclaw message

Single outbound command for sending messages and channel actions across Discord, Google Chat, iMessage, Matrix, Mattermost (plugin), Microsoft Teams, Signal, Slack, Telegram, and WhatsApp.

openclaw message <subcommand> [flags]

Channel selection

• --channel <name> is required if more than one channel is configured; with exactly one channel configured, that channel is the default.
• Values: discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp (Mattermost requires the plugin).
• Channel-prefixed targets (for example discord:channel:123) resolve the owning plugin without an explicit --channel.

With an explicit channel, Gateway-owned actions such as read --channel discord validate config without running local state migrations. They require a reachable Gateway. Local actions, broadcasts, dry-runs, and commands that need local channel discovery retain local config and plugin preparation.

Agent ownership

openclaw message uses the configured System Agent as its agent owner, falling back to a retained legacy owner or the sole configured agent when the System Agent is unset.

In an explicit multi-agent configuration without an owner, the command stops before sending. Choose an existing agent ID from openclaw agents list, set it as the System Agent, then retry:

openclaw config set agents.defaults.systemAgent.agentId <id>

This setting also selects the owner for other ambient system work. The message command does not accept --agent; --channel and --account select the channel and channel account.

Target formats (-t, --target)

Channel name lookup: for providers with a directory (Discord/Slack/etc), names like Help or #help resolve via the directory cache, falling back to a live directory lookup on a cache miss where the provider supports it.

Common flags

Every action accepts: --channel <name>, --account <id>, --json, --dry-run, --verbose. Actions that take a destination also accept -t, --target <dest>.

An explicitly empty or whitespace-only --account value is rejected. Omit the option to use the existing default or bound account, including when a shell variable is empty. Nonblank account values keep their existing selection rules.

An explicitly empty or whitespace-only --channel value is also rejected. Omit the option to select the sole configured channel, or use a channel-prefixed target when supported.

Discord message bodies, captions, poll context, and component text retain leading indentation. Existing empty-message validation still applies. Ordinary message and caption delivery still trims trailing whitespace.

Local message actions run the loaded plugins' shutdown hooks before exiting, including after an action fails. These hooks have a 2.5-second overall budget and do not change the action's exit status. message read skips these shutdown hooks. The executable then drains shared-state database workers within its existing five-second cleanup budget. If plugin disposal is still pending, it records a deferral and schedules that drain after disposal settles, preserving state for unfinished writes without making the command wait again. Cleanup warnings preserve the action's result; they do not claim the unfinished cleanup completed.

SecretRef resolution

openclaw message resolves channel SecretRefs before running the action, scoped as narrowly as possible:

• channel-scoped when --channel is set (or inferred from a prefixed target)
• account-scoped when --account is also set
• all configured channels when neither is set

Unresolved SecretRefs on unrelated channels never block a targeted action; an unresolved SecretRef on the selected channel/account fails the action closed.

Actions

Core

Reaction listings show labels, counts, and available users as plain terminal text. Use --json for the complete channel result.

The legacy message read --include-thread spelling remains accepted for existing scripts but has no effect.

Member info

Use --channel-id to select a Matrix room or a Microsoft Teams standard channel. Teams requires the Graph <team-id>/<channel-id> form because the CLI has no current conversation. Provider access and membership checks still apply.

openclaw message member info --channel matrix \  --channel-id '!room:example.org' --user-id '@member:example.org' openclaw message member info --channel msteams \  --channel-id '<team-id>/<channel-id>' --user-id '<aad-object-id>'

Send

openclaw message send --channel discord \  --target channel:123 --message "hi" --reply-to 456

• --media <path-or-url>: attach image/audio/video/document (local path or URL). Repeat to send multiple files in order; Telegram groups consecutive photos into albums.
• --presentation <json>: shared payload with text, context, divider, chart, table, buttons, and select blocks, rendered per channel capability. See Message Presentation.
• --delivery <json>: generic delivery preferences, for example {"pin": true}. --pin is shorthand for pinned delivery when the channel supports it.
• --reply-to <id>, --thread-id <id> (Telegram forum topic; Slack thread timestamp, same field as --reply-to).
• --force-document: preserve original image bytes on Slack, or send images/GIFs/videos as documents on Telegram and WhatsApp, to avoid channel compression.
• --silent (Telegram, Discord): send without a notification.
• --gif-playback (WhatsApp only): treat video media as GIF playback.

When a send is suppressed by a message hook, fails, or only partially succeeds, the command explains the outcome and exits nonzero. Partial delivery keeps any confirmed message ID. JSON failures include ok: false, deliveryStatus, and error; successful JSON responses retain their existing shape.

openclaw message send --channel discord \  --target channel:123 --message "Choose:" \  --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}'

openclaw message send --channel telegram --target @mychat --message "Choose:" \  --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}'

Slack renders supported chart blocks natively; other channels receive the same data as readable text:

openclaw message send --channel slack --target channel:C123 \  --presentation '{"blocks":[{"type":"chart","chartType":"bar","title":"Quarterly revenue","categories":["Q1","Q2"],"series":[{"name":"Revenue","values":[120,145]}],"xLabel":"Quarter"}]}'

Slack also renders explicit table blocks natively. Other channels receive the caption and every row in a fixed text format:

openclaw message send --channel slack --target channel:C123 \  --presentation '{"title":"Pipeline report","blocks":[{"type":"table","caption":"Open pipeline","headers":["Account","Stage","ARR"],"rows":[["Acme","Won",125000],["Globex","Review",82000]],"rowHeaderColumnIndex":0}]}'

Telegram Mini App buttons use webApp (web_app still parses for legacy JSON) and only render in private chats between a user and the bot:

openclaw message send --channel telegram --target 123456789 --message "Open app:" \  --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Launch","webApp":{"url":"https://example.com/app"}}]}]}'

openclaw message send --channel telegram --target @mychat \  --media ./diagram.png --force-document

openclaw message send --channel telegram --target @mychat \  --message "Trip photos" --media ./photo-1.jpg --media ./photo-2.jpg

openclaw message send --channel msteams \  --target conversation:19:abc@thread.tacv2 \  --presentation '{"title":"Status update","blocks":[{"type":"text","text":"Build completed"}]}'

Poll

openclaw message poll --channel discord \  --target channel:123 \  --poll-question "Snack?" \  --poll-option Pizza --poll-option Sushi \  --poll-multi --poll-duration-hours 48

• --poll-option <choice>: repeat 2-12 times.
• --poll-multi: allow multiple selections.
• Discord: --poll-duration-hours, --silent, --message.
• Telegram: --poll-duration-seconds <n> (5-604800; up to seven days), --silent, --poll-anonymous / --poll-public, --thread-id.

openclaw message poll --channel telegram \  --target @mychat \  --poll-question "Lunch?" \  --poll-option Pizza --poll-option Sushi \  --poll-duration-seconds 120 --silent

openclaw message poll --channel msteams \  --target conversation:19:abc@thread.tacv2 \  --poll-question "Lunch?" \  --poll-option Pizza --poll-option Sushi

Threads

• thread create: channels Discord. Required: --thread-name, --target (channel id). Optional: --message-id, --message, --auto-archive-min.
• thread list: channels Discord. Required: --guild-id. Optional: --channel-id, --include-archived, --before, --limit.
• thread reply: channels Discord. Required: --target (thread id), --message. Optional: --media, --reply-to.

Emojis

• emoji list: Discord (--guild-id), Slack (no extra flags).
• emoji upload: Discord. Required: --guild-id, --emoji-name, --media. Optional: --role-ids (repeat).

Stickers

• sticker send: Discord. Required: --target, --sticker-id (repeat). Optional: --message.
• sticker upload: Discord. Required: --guild-id, --sticker-name, --sticker-desc, --sticker-tags, --media.

Roles, channels, voice, events (Discord)

• role info: --guild-id.
• role add / role remove: --guild-id, --user-id, --role-id.
• channel info: --target.
• channel list: --guild-id.
• voice status: --guild-id, --user-id.
• event list: --guild-id.
• event create: required --guild-id, --event-name, --start-time; optional --end-time, --desc, --channel-id, --location, --event-type, --image <url-or-path>.

Moderation (Discord)

• timeout: --guild-id, --user-id; optional --duration-min or --until (omit both to clear the timeout), --reason.
• kick: --guild-id, --user-id, --reason.
• ban: --guild-id, --user-id, --delete-days, --reason.

Broadcast

openclaw message broadcast --targets <target...> [--channel all] [--message <text>] [--media <url>] [--dry-run]

Sends one payload to multiple targets. --targets takes a space-separated list. Use --channel all to target every configured provider.

If any target fails, is suppressed, or only partially delivers, the broadcast exits nonzero. Text output identifies failed targets; JSON reports ok: false and retains every target's result, including failures returned by channel plugins.

Related

• CLI reference
• Agent send
• Message Presentation