# Tinyagi Tinyagi Tinyagi

> Send User Message

- Skill: `tomevault-io/tinyagi-tinyagi-tinyagi` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/tinyagi-tinyagi-tinyagi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/tinyagi-tinyagi-tinyagi/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/tinyagi-tinyagi-tinyagi

---


# 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

---
> Source: [TinyAGI/tinyagi](https://github.com/TinyAGI/tinyagi) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->