Message

text

Copy

openclaw message

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

Usage

text
Copy
openclaw message <subcommand> [flags]

Channel selection:

• text

  Copy

  --channel
  required if more than one channel is configured.
• If exactly one channel is configured, it becomes the default.
• Values:
  text

  Copy

  discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp
  (Mattermost requires plugin)
• text

  Copy

  openclaw message
  resolves the selected channel to its owning plugin when
  text

  Copy

  --channel
  or a channel-prefixed target is present; otherwise it loads configured channel plugins for default-channel inference.

Target formats (

):

• WhatsApp: E.164 or group JID
• Telegram: chat id or
  text

  Copy

  @username
• Discord:
  text

  Copy

  channel:<id>
  or
  text

  Copy

  user:<id>
  (or
  text

  Copy

  <@id>
  mention; raw numeric ids are treated as channels)
• Google Chat:
  text

  Copy

  spaces/<spaceId>
  or
  text

  Copy

  users/<userId>
• Slack:
  text

  Copy

  channel:<id>
  or
  text

  Copy

  user:<id>
  (raw channel id is accepted)
• Mattermost (plugin):
  text

  Copy

  channel:<id>
  ,
  text

  Copy

  user:<id>
  , or
  text

  Copy

  @username
  (bare ids are treated as channels)
• Signal:
  text

  Copy

  +E.164
  ,
  text

  Copy

  group:<id>
  ,
  text

  Copy

  signal:+E.164
  ,
  text

  Copy

  signal:group:<id>
  , or
  text

  Copy

  username:<name>
  /
  text

  Copy

  u:<name>
• iMessage: handle,
  text

  Copy

  chat_id:<id>
  ,
  text

  Copy

  chat_guid:<guid>
  , or
  text

  Copy

  chat_identifier:<id>
• Matrix:
  text

  Copy

  @user:server
  ,
  text

  Copy

  !room:server
  , or
  text

  Copy

  #alias:server
• Microsoft Teams: conversation id (
  text

  Copy

  19:...@thread.tacv2
  ) or
  text

  Copy

  conversation:<id>
  or
  text

  Copy

  user:<aad-object-id>

Name lookup:

• For supported providers (Discord/Slack/etc), channel names like
  text

  Copy

  Help
  or
  text

  Copy

  #help
  are resolved via the directory cache.
• On cache miss, OpenClaw will attempt a live directory lookup when the provider supports it.

Common flags

• text

  Copy

  --channel <name>
• text

  Copy

  --account <id>
• text

  Copy

  --target <dest>
  (target channel or user for send/poll/read/etc)
• text

  Copy

  --targets <name>
  (repeat; broadcast only)
• text

  Copy

  --json
• text

  Copy

  --dry-run
• text

  Copy

  --verbose

SecretRef behavior

• text

  Copy

  openclaw message
  resolves supported channel SecretRefs before running the selected action.
• Resolution is scoped to the active action target when possible:
  • channel-scoped when
    text

    Copy

    --channel
    is set (or inferred from prefixed targets like
    text

    Copy

    discord:...
    )
  • account-scoped when
    text

    Copy

    --account
    is set (channel globals + selected account surfaces)
  • when
    text

    Copy

    --account
    is omitted, OpenClaw does not force a
    text

    Copy

    default
    account SecretRef scope
• Unresolved SecretRefs on unrelated channels do not block a targeted message action.
• If the selected channel/account SecretRef is unresolved, the command fails closed for that action.

Actions

Core

• text

  Copy

  send
  • Channels: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams
  • Required:
    text

    Copy

    --target
    , plus
    text

    Copy

    --message
    ,
    text

    Copy

    --media
    , or
    text

    Copy

    --presentation
  • Optional:
    text

    Copy

    --media
    ,
    text

    Copy

    --presentation
    ,
    text

    Copy

    --delivery
    ,
    text

    Copy

    --pin
    ,
    text

    Copy

    --reply-to
    ,
    text

    Copy

    --thread-id
    ,
    text

    Copy

    --gif-playback
    ,
    text

    Copy

    --force-document
    ,
    text

    Copy

    --silent
  • Shared presentation payloads:
    text

    Copy

    --presentation
    sends semantic blocks (
    text

    Copy

    text
    ,
    text

    Copy

    context
    ,
    text

    Copy

    divider
    ,
    text

    Copy

    buttons
    ,
    text

    Copy

    select
    ) that core renders through the selected channel's declared capabilities. See Message Presentation.
  • Generic delivery preferences:
    text

    Copy

    --delivery
    accepts delivery hints such as
    text

    Copy

    { "pin": true }
    ;
    text

    Copy

    --pin
    is shorthand for pinned delivery when the channel supports it.
  • Telegram only:
    text

    Copy

    --force-document
    (send images and GIFs as documents to avoid Telegram compression)
  • Telegram only:
    text

    Copy

    --thread-id
    (forum topic id)
  • Slack only:
    text

    Copy

    --thread-id
    (thread timestamp;
    text

    Copy

    --reply-to
    uses the same field)
  • Telegram + Discord:
    text

    Copy

    --silent
  • WhatsApp only:
    text

    Copy

    --gif-playback

• text

  Copy

  poll
  • Channels: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
  • Required:
    text

    Copy

    --target
    ,
    text

    Copy

    --poll-question
    ,
    text

    Copy

    --poll-option
    (repeat)
  • Optional:
    text

    Copy

    --poll-multi
  • Discord only:
    text

    Copy

    --poll-duration-hours
    ,
    text

    Copy

    --silent
    ,
    text

    Copy

    --message
  • Telegram only:
    text

    Copy

    --poll-duration-seconds
    (5-600),
    text

    Copy

    --silent
    ,
    text

    Copy

    --poll-anonymous
    /
    text

    Copy

    --poll-public
    ,
    text

    Copy

    --thread-id

• text

  Copy

  react
  • Channels: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
  • Required:
    text

    Copy

    --message-id
    ,
    text

    Copy

    --target
  • Optional:
    text

    Copy

    --emoji
    ,
    text

    Copy

    --remove
    ,
    text

    Copy

    --participant
    ,
    text

    Copy

    --from-me
    ,
    text

    Copy

    --target-author
    ,
    text

    Copy

    --target-author-uuid
  • Note:
    text

    Copy

    --remove
    requires
    text

    Copy

    --emoji
    (omit
    text

    Copy

    --emoji
    to clear own reactions where supported; see /tools/reactions)
  • WhatsApp only:
    text

    Copy

    --participant
    ,
    text

    Copy

    --from-me
  • Signal group reactions:
    text

    Copy

    --target-author
    or
    text

    Copy

    --target-author-uuid
    required

• text

  Copy

  reactions
  • Channels: Discord/Google Chat/Slack/Matrix
  • Required:
    text

    Copy

    --message-id
    ,
    text

    Copy

    --target
  • Optional:
    text

    Copy

    --limit

• text

  Copy

  read
  • Channels: Discord/Slack/Matrix
  • Required:
    text

    Copy

    --target
  • Optional:
    text

    Copy

    --limit
    ,
    text

    Copy

    --before
    ,
    text

    Copy

    --after
  • Discord only:
    text

    Copy

    --around

• text

  Copy

  edit
  • Channels: Discord/Slack/Matrix
  • Required:
    text

    Copy

    --message-id
    ,
    text

    Copy

    --message
    ,
    text

    Copy

    --target

• text

  Copy

  delete
  • Channels: Discord/Slack/Telegram/Matrix
  • Required:
    text

    Copy

    --message-id
    ,
    text

    Copy

    --target

• text

  Copy

  pin
  /
  text

  Copy

  unpin
  • Channels: Discord/Slack/Matrix
  • Required:
    text

    Copy

    --message-id
    ,
    text

    Copy

    --target

• text

  Copy

  pins
  (list)
  • Channels: Discord/Slack/Matrix
  • Required:
    text

    Copy

    --target

• text

  Copy

  permissions
  • Channels: Discord/Matrix
  • Required:
    text

    Copy

    --target
  • Matrix only: available when Matrix encryption is enabled and verification actions are allowed

• text

  Copy

  search
  • Channels: Discord
  • Required:
    text

    Copy

    --guild-id
    ,
    text

    Copy

    --query
  • Optional:
    text

    Copy

    --channel-id
    ,
    text

    Copy

    --channel-ids
    (repeat),
    text

    Copy

    --author-id
    ,
    text

    Copy

    --author-ids
    (repeat),
    text

    Copy

    --limit

Threads

• text

  Copy

  thread create
  • Channels: Discord
  • Required:
    text

    Copy

    --thread-name
    ,
    text

    Copy

    --target
    (channel id)
  • Optional:
    text

    Copy

    --message-id
    ,
    text

    Copy

    --message
    ,
    text

    Copy

    --auto-archive-min

• text

  Copy

  thread list
  • Channels: Discord
  • Required:
    text

    Copy

    --guild-id
  • Optional:
    text

    Copy

    --channel-id
    ,
    text

    Copy

    --include-archived
    ,
    text

    Copy

    --before
    ,
    text

    Copy

    --limit

• text

  Copy

  thread reply
  • Channels: Discord
  • Required:
    text

    Copy

    --target
    (thread id),
    text

    Copy

    --message
  • Optional:
    text

    Copy

    --media
    ,
    text

    Copy

    --reply-to

Emojis

• text

  Copy

  emoji list
  • Discord:
    text

    Copy

    --guild-id
  • Slack: no extra flags

• text

  Copy

  emoji upload
  • Channels: Discord
  • Required:
    text

    Copy

    --guild-id
    ,
    text

    Copy

    --emoji-name
    ,
    text

    Copy

    --media
  • Optional:
    text

    Copy

    --role-ids
    (repeat)

Stickers

• text

  Copy

  sticker send
  • Channels: Discord
  • Required:
    text

    Copy

    --target
    ,
    text

    Copy

    --sticker-id
    (repeat)
  • Optional:
    text

    Copy

    --message

• text

  Copy

  sticker upload
  • Channels: Discord
  • Required:
    text

    Copy

    --guild-id
    ,
    text

    Copy

    --sticker-name
    ,
    text

    Copy

    --sticker-desc
    ,
    text

    Copy

    --sticker-tags
    ,
    text

    Copy

    --media

Roles / Channels / Members / Voice

• text

  Copy

  role info
  (Discord):
  text

  Copy

  --guild-id
• text

  Copy

  role add
  /
  text

  Copy

  role remove
  (Discord):
  text

  Copy

  --guild-id
  ,
  text

  Copy

  --user-id
  ,
  text

  Copy

  --role-id
• text

  Copy

  channel info
  (Discord):
  text

  Copy

  --target
• text

  Copy

  channel list
  (Discord):
  text

  Copy

  --guild-id
• text

  Copy

  member info
  (Discord/Slack):
  text

  Copy

  --user-id
  (+
  text

  Copy

  --guild-id
  for Discord)
• text

  Copy

  voice status
  (Discord):
  text

  Copy

  --guild-id
  ,
  text

  Copy

  --user-id

Events

• text

  Copy

  event list
  (Discord):
  text

  Copy

  --guild-id
• text

  Copy

  event create
  (Discord):
  text

  Copy

  --guild-id
  ,
  text

  Copy

  --event-name
  ,
  text

  Copy

  --start-time
  • Optional:
    text

    Copy

    --end-time
    ,
    text

    Copy

    --desc
    ,
    text

    Copy

    --channel-id
    ,
    text

    Copy

    --location
    ,
    text

    Copy

    --event-type

Moderation (Discord)

• text

  Copy

  timeout
  :
  text

  Copy

  --guild-id
  ,
  text

  Copy

  --user-id
  (optional
  text

  Copy

  --duration-min
  or
  text

  Copy

  --until
  ; omit both to clear timeout)
• text

  Copy

  kick
  :
  text

  Copy

  --guild-id
  ,
  text

  Copy

  --user-id
  (+
  text

  Copy

  --reason
  )
• text

  Copy

  ban
  :
  text

  Copy

  --guild-id
  ,
  text

  Copy

  --user-id
  (+
  text

  Copy

  --delete-days
  ,
  text

  Copy

  --reason
  )
  • text

    Copy

    timeout
    also supports
    text

    Copy

    --reason

Broadcast

• text

  Copy

  broadcast
  • Channels: any configured channel; use
    text

    Copy

    --channel all
    to target all providers
  • Required:
    text

    Copy

    --targets <target...>
  • Optional:
    text

    Copy

    --message
    ,
    text

    Copy

    --media
    ,
    text

    Copy

    --dry-run

Examples

Send a Discord reply:

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

Send a message with semantic buttons:

text
Copy
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"}]}]}'

Core renders the same

payload into Discord components, Slack blocks, Telegram inline buttons, Mattermost props, or Teams/Feishu cards depending on channel capability. See Message Presentation for the full contract and fallback rules.

Send a richer presentation payload:

bash
Copy
openclaw message send --channel googlechat --target spaces/AAA... \
  --message "Choose:" \
  --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Choose a path"},{"type":"buttons","buttons":[{"label":"Approve","value":"approve"},{"label":"Decline","value":"decline"}]}]}'

Create a Discord poll:

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

Create a Telegram poll (auto-close in 2 minutes):

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

Send a Teams proactive message:

text
Copy
openclaw message send --channel msteams \
  --target conversation:19:abc@thread.tacv2 --message "hi"

Create a Teams poll:

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

React in Slack:

text
Copy
openclaw message react --channel slack \
  --target C123 --message-id 456 --emoji "✅"

React in a Signal group:

text
Copy
openclaw message react --channel signal \
  --target signal:group:abc123 --message-id 1737630212345 \
  --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000

Send Telegram inline buttons through generic presentation:

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

Send a Teams card through generic presentation:

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

Send a Telegram image as a document to avoid compression:

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

Related

• CLI reference
• Agent send