let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: unify message cli and tools

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-09 08:27:17 +01:00
parent 77d4bb8dfe
commit 721183e259
27 changed files with 2391 additions and 776 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/automation/poll.md
View File

@@ -15,18 +15,22 @@ read_when:
```bash
# WhatsApp
clawdbot message poll --to +15555550123 -q "Lunch today?" -o "Yes" -o "No" -o "Maybe"
clawdbot message poll --to 123456789@g.us -q "Meeting time?" -o "10am" -o "2pm" -o "4pm" -s 2
clawdbot message --action poll --to +15555550123 \
--poll-question "Lunch today?" --poll-option "Yes" --poll-option "No" --poll-option "Maybe"
clawdbot message --action poll --to 123456789@g.us \
--poll-question "Meeting time?" --poll-option "10am" --poll-option "2pm" --poll-option "4pm" --poll-multi
# Discord
clawdbot message poll --to channel:123456789 -q "Snack?" -o "Pizza" -o "Sushi" --provider discord
clawdbot message poll --to channel:123456789 -q "Plan?" -o "A" -o "B" --provider discord --duration-hours 48
clawdbot message --action poll --provider discord --to channel:123456789 \
--poll-question "Snack?" --poll-option "Pizza" --poll-option "Sushi"
clawdbot message --action poll --provider discord --to channel:123456789 \
--poll-question "Plan?" --poll-option "A" --poll-option "B" --poll-duration-hours 48
```
Options:
- `--provider`: `whatsapp` (default) or `discord`
- `--max-selections`: how many choices a voter can select (default: 1)
- `--duration-hours`: Discord-only (defaults to 24 when omitted)
- `--poll-multi`: allow selecting multiple options
- `--poll-duration-hours`: Discord-only (defaults to 24 when omitted)
## Gateway RPC
@@ -45,10 +49,7 @@ Params:
- WhatsApp: 2-12 options, `maxSelections` must be within option count, ignores `durationHours`.
- Discord: 2-10 options, `durationHours` clamped to 1-768 hours (default 24). `maxSelections > 1` enables multi-select; Discord does not support a strict selection count.
## Agent tool (Discord)
The Discord tool action `poll` still uses `question`, `answers`, optional `allowMultiselect`, `durationHours`, and `content`. The gateway/CLI poll model maps `allowMultiselect` to `maxSelections > 1`.
Note: Discord has no “pick exactly N” mode; `maxSelections` is treated as a boolean (`> 1` = multiselect).
## Agent tool (Message)
Use the `message` tool with `poll` action (`to`, `question`, `options`, optional `maxSelections`, `durationHours`, `provider`).
Use the `message` tool with `poll` action (`to`, `pollQuestion`, `pollOption`, optional `pollMulti`, `pollDurationHours`, `provider`).
Note: Discord has no “pick exactly N” mode; `pollMulti` maps to multi-select.

35
docs/cli/index.md
View File

@@ -56,8 +56,6 @@ clawdbot [--dev] [--profile <name>] <command>
info
check
message
send
poll
agent
agents
list
@@ -285,37 +283,10 @@ Options:
## Messaging + agent
### `message send`
Send a message through a provider.
### `message`
Unified outbound messaging + provider actions.
Required:
- `--to <dest>`
- `--message <text>`
Options:
- `--media <path-or-url>`
- `--gif-playback`
- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
- `--account <id>` (WhatsApp)
- `--dry-run`
- `--json`
- `--verbose`
### `message poll`
Create a poll (WhatsApp or Discord).
Required:
- `--to <id>`
- `--question <text>`
- `--option <choice>` (repeat 2-12 times)
Options:
- `--max-selections <n>`
- `--duration-hours <n>` (Discord)
- `--provider <whatsapp|discord>`
- `--dry-run`
- `--json`
- `--verbose`
See: [/cli/message](/cli/message)
### `agent`
Run one agent turn via the Gateway (or `--local` embedded).

210
docs/cli/message.md Normal file
View File

@@ -0,0 +1,210 @@
---
summary: "CLI reference for `clawdbot message` (send + provider actions)"
read_when:
- Adding or modifying message CLI actions
- Changing outbound provider behavior
---
# `clawdbot message`
Single outbound command for sending messages and provider actions
(Discord/Slack/Telegram/WhatsApp/Signal/iMessage).
## Usage
```
clawdbot message --action <action> [--provider <name>] [flags]
```
Defaults:
- `--action send`
Provider selection:
- `--provider` required if more than one provider is configured.
- If exactly one provider is configured, it becomes the default.
- Values: `whatsapp|telegram|discord|slack|signal|imessage`
Target formats (`--to`):
- WhatsApp: E.164 or group JID
- Telegram: chat id or `@username`
- Discord/Slack: `channel:<id>` or `user:<id>` (raw id ok)
- Signal: E.164, `group:<id>`, or `signal:+E.164`
- iMessage: handle or `chat_id:<id>`
## Common flags
- `--to <dest>`
- `--message <text>`
- `--media <url>`
- `--message-id <id>`
- `--reply-to <id>`
- `--thread-id <id>` (Telegram forum thread)
- `--account <id>` (multi-account providers)
- `--dry-run`
- `--json`
- `--verbose`
## Actions
### `send`
Providers: whatsapp, telegram, discord, slack, signal, imessage
Required: `--to`, `--message`
Optional: `--media`, `--reply-to`, `--thread-id`, `--account`, `--gif-playback`
### `react`
Providers: discord, slack, telegram, whatsapp
Required: `--to`, `--message-id`
Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--account`
### `reactions`
Providers: discord, slack
Required: `--to`, `--message-id`
Optional: `--limit`
### `read`
Providers: discord, slack
Required: `--to`
Optional: `--limit`, `--before`, `--after`, `--around`
### `edit`
Providers: discord, slack
Required: `--to`, `--message-id`, `--message`
### `delete`
Providers: discord, slack
Required: `--to`, `--message-id`
### `pin`
Providers: discord, slack
Required: `--to`, `--message-id`
### `unpin`
Providers: discord, slack
Required: `--to`, `--message-id`
### `list-pins`
Providers: discord, slack
Required: `--to`
### `poll`
Providers: whatsapp, discord
Required: `--to`, `--poll-question`, `--poll-option` (repeat)
Optional: `--poll-multi`, `--poll-duration-hours`, `--message`
### `sticker`
Providers: discord
Required: `--to`, `--sticker-id` (repeat)
Optional: `--message`
### `permissions`
Providers: discord
Required: `--to` (channel id)
### `thread-create`
Providers: discord
Required: `--to` (channel id), `--thread-name`
Optional: `--message-id`, `--auto-archive-min`
### `thread-list`
Providers: discord
Required: `--guild-id`
Optional: `--channel-id`, `--include-archived`, `--before`, `--limit`
### `thread-reply`
Providers: discord
Required: `--to` (thread id), `--message`
Optional: `--media`, `--reply-to`
### `search`
Providers: discord
Required: `--guild-id`, `--query`
Optional: `--channel-id`, `--channel-ids`, `--author-id`, `--author-ids`, `--limit`
### `member-info`
Providers: discord, slack
Required: `--user-id`
Discord only: also `--guild-id`
### `role-info`
Providers: discord
Required: `--guild-id`
### `emoji-list`
Providers: discord, slack
Discord only: `--guild-id`
### `emoji-upload`
Providers: discord
Required: `--guild-id`, `--emoji-name`, `--media`
Optional: `--role-ids` (repeat)
### `sticker-upload`
Providers: discord
Required: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
### `role-add`
Providers: discord
Required: `--guild-id`, `--user-id`, `--role-id`
### `role-remove`
Providers: discord
Required: `--guild-id`, `--user-id`, `--role-id`
### `channel-info`
Providers: discord
Required: `--channel-id`
### `channel-list`
Providers: discord
Required: `--guild-id`
### `voice-status`
Providers: discord
Required: `--guild-id`, `--user-id`
### `event-list`
Providers: discord
Required: `--guild-id`
### `event-create`
Providers: discord
Required: `--guild-id`, `--event-name`, `--start-time`
Optional: `--end-time`, `--desc`, `--channel-id`, `--location`, `--event-type`
### `timeout`
Providers: discord
Required: `--guild-id`, `--user-id`
Optional: `--duration-min`, `--until`, `--reason`
### `kick`
Providers: discord
Required: `--guild-id`, `--user-id`
Optional: `--reason`
### `ban`
Providers: discord
Required: `--guild-id`, `--user-id`
Optional: `--reason`, `--delete-days`
## Examples
Send a Discord reply:
```
clawdbot message --action send --provider discord \
--to channel:123 --message "hi" --reply-to 456
```
Create a Discord poll:
```
clawdbot message --action poll --provider discord \
--to channel:123 \
--poll-question "Snack?" \
--poll-option Pizza --poll-option Sushi \
--poll-multi --poll-duration-hours 48
```
React in Slack:
```
clawdbot message --action react --provider slack \
--to C123 --message-id 456 --emoji "✅"
```

2
docs/gateway/index.md
View File

@@ -254,7 +254,7 @@ Windows installs should use **WSL2** and follow the Linux systemd section above.
## CLI helpers
- `clawdbot gateway health|status` — request health/status over the Gateway WS.
- `clawdbot message send --to <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
- `clawdbot message --to <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
- `clawdbot agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
- `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- `clawdbot daemon stop|restart` — stop/restart the supervised gateway service (launchd/systemd).

2
docs/index.md
View File

@@ -134,7 +134,7 @@ clawdbot gateway --port 19001
Send a test message (requires a running Gateway):
```bash
clawdbot message send --to +15555550123 --message "Hello from CLAWDBOT"
clawdbot message --to +15555550123 --message "Hello from CLAWDBOT"
```
## Configuration (optional)

6
docs/nodes/images.md
View File

@@ -8,12 +8,12 @@ read_when:
CLAWDBOT is now **web-only** (Baileys). This document captures the current media handling rules for send, gateway, and agent replies.
## Goals
- Send media with optional captions via `clawdbot message send --media`.
- Send media with optional captions via `clawdbot message --media`.
- Allow auto-replies from the web inbox to include media alongside text.
- Keep per-type limits sane and predictable.
## CLI Surface
- `clawdbot message send --media <path-or-url> [--message <caption>]`
- `clawdbot message --media <path-or-url> [--message <caption>]`
- `--media` optional; caption can be empty for media-only sends.
- `--dry-run` prints the resolved payload; `--json` emits `{ provider, to, messageId, mediaUrl, caption }`.
@@ -30,7 +30,7 @@ CLAWDBOT is now **web-only** (Baileys). This document captures the current media
## Auto-Reply Pipeline
- `getReplyFromConfig` returns `{ text?, mediaUrl?, mediaUrls? }`.
- When media is present, the web sender resolves local paths or URLs using the same pipeline as `clawdbot message send`.
- When media is present, the web sender resolves local paths or URLs using the same pipeline as `clawdbot message`.
- Multiple media entries are sent sequentially if provided.
## Inbound Media to Commands (Pi)

2
docs/providers/telegram.md
View File

@@ -223,7 +223,7 @@ Outbound Telegram API calls retry on transient network/429 errors with exponenti
## Delivery targets (CLI/cron)
- Use a chat id (`123456789`) or a username (`@name`) as the target.
- Example: `clawdbot message send --provider telegram --to 123456789 --message "hi"`.
- Example: `clawdbot message --provider telegram --to 123456789 --message "hi"`.
## Troubleshooting

2
docs/providers/whatsapp.md
View File

@@ -158,7 +158,7 @@ Behavior:
- Caption only on first media item.
- Media fetch supports HTTP(S) and local paths.
- Animated GIFs: WhatsApp expects MP4 with `gifPlayback: true` for inline looping.
- CLI: `clawdbot message send --media <mp4> --gif-playback`
- CLI: `clawdbot message --media <mp4> --gif-playback`
- Gateway: `send` params include `gifPlayback: true`
## Media limits + optimization

2
docs/start/faq.md
View File

@@ -560,7 +560,7 @@ Outbound attachments from the agent must include a `MEDIA:<path-or-url>` line (o
CLI sending:
```bash
clawdbot message send --to +15555550123 --message "Here you go" --media /path/to/file.png
clawdbot message --to +15555550123 --message "Here you go" --media /path/to/file.png
```
Note: images are resized/recompressed (max side 2048px) to hit size limits. See [Images](/nodes/images).

2
docs/start/getting-started.md
View File

@@ -152,7 +152,7 @@ In a new terminal:
```bash
clawdbot health
clawdbot message send --to +15555550123 --message "Hello from Clawdbot"
clawdbot message --to +15555550123 --message "Hello from Clawdbot"
```
If `health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.

83
docs/tools/index.md
View File

@@ -149,15 +149,28 @@ Notes:
- Uses the image model directly (independent of the main chat model).
### `message`
Send messages and polls across providers.
Send messages and provider actions across Discord/Slack/Telegram/WhatsApp/Signal/iMessage.
Core actions:
- `send` (text + optional media)
- `poll` (WhatsApp/Discord polls)
- `react` / `reactions` / `read` / `edit` / `delete`
- `pin` / `unpin` / `list-pins`
- `permissions`
- `thread-create` / `thread-list` / `thread-reply`
- `search`
- `sticker`
- `member-info` / `role-info`
- `emoji-list` / `emoji-upload` / `sticker-upload`
- `role-add` / `role-remove`
- `channel-info` / `channel-list`
- `voice-status`
- `event-list` / `event-create`
- `timeout` / `kick` / `ban`
Notes:
- `send` routes WhatsApp via the Gateway and other providers directly.
- `poll` always routes via the Gateway.
- `send` routes WhatsApp via the Gateway; other providers go direct.
- `poll` uses the Gateway for WhatsApp and direct Discord API for Discord.
### `cron`
Manage Gateway cron jobs and wakeups.
@@ -209,70 +222,6 @@ Notes:
- Result is restricted to per-agent allowlists (`routing.agents.<agentId>.subagents.allowAgents`).
- When `["*"]` is configured, the tool includes all configured agents and marks `allowAny: true`.
### `discord`
Send Discord reactions, stickers, or polls.
Core actions:
- `react` (`channelId`, `messageId`, `emoji`)
- `reactions` (`channelId`, `messageId`, optional `limit`)
- `sticker` (`to`, `stickerIds`, optional `content`)
- `poll` (`to`, `question`, `answers`, optional `allowMultiselect`, `durationHours`, `content`)
- `permissions` (`channelId`)
- `readMessages` (`channelId`, optional `limit`/`before`/`after`/`around`)
- `sendMessage` (`to`, `content`, optional `mediaUrl`, `replyTo`)
- `editMessage` (`channelId`, `messageId`, `content`)
- `deleteMessage` (`channelId`, `messageId`)
- `threadCreate` (`channelId`, `name`, optional `messageId`, `autoArchiveMinutes`)
- `threadList` (`guildId`, optional `channelId`, `includeArchived`, `before`, `limit`)
- `threadReply` (`channelId`, `content`, optional `mediaUrl`, `replyTo`)
- `pinMessage`/`unpinMessage` (`channelId`, `messageId`)
- `listPins` (`channelId`)
- `searchMessages` (`guildId`, `content`, optional `channelId`/`channelIds`, `authorId`/`authorIds`, `limit`)
- `memberInfo` (`guildId`, `userId`)
- `roleInfo` (`guildId`)
- `emojiList` (`guildId`)
- `roleAdd`/`roleRemove` (`guildId`, `userId`, `roleId`)
- `channelInfo` (`channelId`)
- `channelList` (`guildId`)
- `voiceStatus` (`guildId`, `userId`)
- `eventList` (`guildId`)
- `eventCreate` (`guildId`, `name`, `startTime`, optional `endTime`, `description`, `channelId`, `entityType`, `location`)
- `timeout` (`guildId`, `userId`, optional `durationMinutes`, `until`, `reason`)
- `kick` (`guildId`, `userId`, optional `reason`)
- `ban` (`guildId`, `userId`, optional `reason`, `deleteMessageDays`)
Notes:
- `to` accepts `channel:<id>` or `user:<id>`.
- Polls require 2–10 answers and default to 24 hours.
- `reactions` returns per-emoji user lists (limited to 100 per reaction).
- Reaction removal semantics: see [/tools/reactions](/tools/reactions).
- `discord.actions.*` gates Discord tool actions; `roles` + `moderation` default to `false`.
- `searchMessages` follows the Discord preview feature constraints (limit max 25, channel/author filters accept arrays).
- The tool is only exposed when the current provider is Discord.
### `whatsapp`
Send WhatsApp reactions.
Core actions:
- `react` (`chatJid`, `messageId`, `emoji`, optional `remove`, `participant`, `fromMe`, `accountId`)
Notes:
- Reaction removal semantics: see [/tools/reactions](/tools/reactions).
- `whatsapp.actions.*` gates WhatsApp tool actions.
- The tool is only exposed when the current provider is WhatsApp.
### `telegram`
Send Telegram messages or reactions.
Core actions:
- `sendMessage` (`to`, `content`, optional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`, optional `remove`)
Notes:
- Reaction removal semantics: see [/tools/reactions](/tools/reactions).
- `telegram.actions.*` gates Telegram tool actions.
- The tool is only exposed when the current provider is Telegram.
## Parameters (common)
Gateway-backed tools (`canvas`, `nodes`, `cron`):