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

apus message <subcommand> [flags]

Channel selection

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

apus 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 apus agents list, set it as the System Agent, then retry:

apus 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 Format
Discord channel:<id>, user:<id>, <@id> mention, or a bare numeric id (treated as a channel id)
Google Chat spaces/<spaceId> or users/<userId>
iMessage handle, chat_id:<id>, chat_guid:<guid>, or chat_identifier:<id>
Mattermost (plugin) channel:<id>, user:<id>, @username, or a bare id (treated as a channel)
Matrix @user:server, !room:server, or #alias:server
Microsoft Teams conversation:<id> (19:...@thread.tacv2), a bare conversation id, or user:<aad-object-id>
Signal +E.164, group:<id>, uuid:<id>, username:<name>/u:<name>, or any of these prefixed with signal:
Slack channel:<id> or user:<id> (a bare id is treated as a channel)
Telegram chat id, @username, or a forum topic target: <chatId>:topic:<topicId> (or --thread-id <topicId>)
WhatsApp E.164, group JID (...@g.us), or Channel/Newsletter JID (...@newsletter)

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

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

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

Actions

Core

Action Channels Required Notes
send Discord, Google Chat, iMessage, Matrix, Mattermost (plugin), Microsoft Teams, Signal, Slack, Telegram, WhatsApp --target, plus one of --message/--media/--presentation See Send below.
poll Discord, Matrix, Microsoft Teams, Telegram, WhatsApp --target, --poll-question, --poll-option (repeat) See Poll below.
react Discord, Matrix, Nextcloud Talk, Signal, Slack, Telegram, WhatsApp --message-id, --target --emoji, --remove (needs --emoji; omit it to clear own reactions where supported, see Reactions). WhatsApp: --participant, --from-me. Signal group reactions require --target-author or --target-author-uuid. Nextcloud Talk only adds reactions; --remove errors.
reactions Discord, Matrix, Microsoft Teams, Slack --message-id, --target --limit.
read Discord, Matrix, Microsoft Teams, Slack --target --limit, --message-id, --before, --after. Discord: --around. Slack: --message-id reads a specific timestamp, combine with --thread-id for an exact thread reply.
edit Discord, Matrix, Microsoft Teams, Slack, Telegram --message-id, --message, --target Telegram forum threads use --thread-id.
delete Discord, Matrix, Microsoft Teams, Slack, Telegram --message-id, --target
pin / unpin Discord, Matrix, Microsoft Teams, Slack --message-id, --target unpin also accepts --pinned-message-id (Microsoft Teams: the pin/list-pins resource id, not the chat message id).
pins (list) Discord, Matrix, Microsoft Teams, Slack --target --limit.
permissions Discord, Matrix --target Matrix: available only when encryption is enabled and verification actions are allowed.
search Discord, Microsoft Teams --query --guild-id (Discord; resolved from --channel-id when omitted), --channel-id (required for Microsoft Teams as Graph <team-id>/<channel-id>), --channel-ids (repeat), --author-id, --author-ids (repeat), --limit.
member info Discord, Matrix, Microsoft Teams, Slack --user-id --channel-id (required for Matrix and Microsoft Teams), --guild-id (Discord).

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.

apus message member info --channel matrix \
  --channel-id '!room:example.org' --user-id '@member:example.org'

apus message member info --channel msteams \
  --channel-id '<team-id>/<channel-id>' --user-id '<aad-object-id>'

Send

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

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.

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

apus 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:

apus 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 as deterministic text:

apus 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:

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

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

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

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

Poll

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

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

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

Threads

Emojis

Stickers

Roles, channels, voice, events (Discord)

Moderation (Discord)

Broadcast

apus 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