send-user-message

# Send User Message Send a message to a paired user via the TinyAGI API server (`POST /api/responses`). The message is delivered by the channel client (Discord, Telegram, or WhatsApp) that polls the API for pending responses. ## When to use - Proactively notify a user (e.g., task completion, status update, alert) - Send a message during a heartbeat invocation (no active user conversation) - Reach a specific user on a specific channel when multiple pairings exist ## Workflow ### 1. Identify the target If you already know the target from the current conversation context (channel and senderId from the incoming message), skip to step 2. If you are running from a heartbeat invocation or are unsure which user to send to, list available targets first: ```bash <skill_dir>/scripts/send-message.sh list-targets ``` This reads `pairing.json` and prints all approved pairings with their `channel`, `senderId`, and `sender` (display name). Pick the appropriate target. ### 2. Send the message ```bash <skill_dir>/scripts/send-message.sh send \ --channel <channel> \ --sender-id <senderId> \ --sender "<display name>" \ --message "<your message>" ``` With file attachments: ```bash <skill_dir>/scripts/send-message.sh send \ --channel telegram \ --sender-id 123456 \ --sender "Alice" \ --message "Here's the report you requested." \ --files "/Users/you/.tinyagi/files/report.pdf,/Users/you/.tinyagi/files/chart.png" ``` Parameters: - `--channel`: One of `discord`, `telegram`, `whatsapp` - `--sender-id`: The channel-specific user ID (from pairing.json or conversation context) - `--sender`: Human-readable display name of the recipient - `--message`: The message text to send (max 4000 chars) - `--agent`: (Optional) Agent ID to attribute the message to - `--files`: (Optional) Comma-separated absolute file paths to attach (files must exist on disk) The script POSTs to `POST /api/responses` which enqueues the message in the SQLite responses table for the channel client to pick up. ### 3. Choosing a target when multiple pairings exist When there are multiple approved pairings and you need to decide who to message: - If the task or context specifies a user by name, match against the `sender` field - If the task specifies a channel, filter by `channel` - If ambiguous, prefer the most recently approved pairing - If still ambiguous, send to all relevant targets (run the send command once per target) ## Notes - The script POSTs to the API server (default `http://localhost:3777`), configurable via `TINYAGI_API_PORT` env var - Messages include a `senderId` field so channel clients can route agent-initiated messages to the correct user - For heartbeat-context messages, set `--agent` to identify which agent is sending