mms-receive

Query received MMS from the Android telephony content provider. Returns structured JSON — sender, timestamp, MIME parts, and saved file paths. Stateless: no polling, no daemon. Callers own the high-water mark.

Platform: Android/Termux only. Confirm before use:

[[ "$(uname -o)" == "Android" ]] && echo "OK" || echo "ERROR: not Android"

---

Agent Dispatch Guide

Full dispatch guide in `AGENTS.md`. Summary:

Activate when the user asks to check for received MMS, download a photo/video/audio message, or poll for new messages since a known ID.

Do not activate for: sending MMS (mms-send), sending SMS (sms-send), reading SMS text (termux-sms-list).

---

Quick Start

mms-receive --limit 5
mms-receive --since 114
mms-receive --no-save
mms-receive --show-config

---

Setup

# Option A — add bin/ to PATH
export PATH="$PATH:/path/to/skill-mms-receive/bin"

# Option B — symlink
ln -s /path/to/skill-mms-receive/bin/mms-receive ~/Scripts/mms-receive

# Option C — tclaw (already on PATH if installed via tclaw)

No additional packages needed — uses /system/bin/content (present on all Android devices) and python3 (standard in Termux).

---

Usage

mms-receive [--limit N] [--since ID] [--save DIR] [--no-save] [--json]
mms-receive --show-config

Flag	Default	Purpose
--limit N	10	Max MMS to return
--since ID	—	Only return _id > ID (high-water mark)
--save DIR	SAVE_DIR from config	Save media parts to this directory
--no-save	false	Return metadata only; do not copy files
--show-config	—	Print effective config as JSON and exit

Output is always JSON to stdout. Each MMS:

{
  "id": 114,
  "date": 1787965805,
  "thread_id": "7",
  "sender": "+15558675309",
  "parts": [
    {
      "id": "149",
      "mime": "video/3gpp",
      "name": "clip.3gp",
      "saved_path": "~/.openclaw/workspace/media/inbound/20260828_210000_+15558675309_114/part_149.3gp",
      "size": 39112
    }
  ]
}

SMIL parts are always filtered. Inline text parts carry a text field instead of saved_path.

---

Configuration File

~/.config/mms-receive — INI-style, KEY = value, # comments.

SAVE_DIR = ~/.openclaw/workspace/media/inbound
LIMIT    = 10

Resolution order:

Priority	Source	How to set
1	~/.config/mms-receive	Edit directly
2	MMS_RECEIVE_SAVE_DIR / MMS_RECEIVE_LIMIT env	.bashrc
3	Built-in default	Warns on stderr

Verify with:

mms-receive --show-config

---

How It Works

1. Queries content://mms/inbox via /system/bin/content as root
2. For each MMS: resolves sender from content://mms/<id>/addr (type 137 = sender)
3. Lists parts from content://mms/<id>/part; skips SMIL
4. For media parts with a file path: copies from telephony storage to SAVE_DIR/<timestamp>_<sender>_<id>/
5. Returns JSON array in chronological order

---

Deprecation Note

This skill is a standalone component. Once openclaw-termux-channel is released, MMS receive will be integrated into that channel plugin and called with --since <id> for polling. This skill remains as a useful standalone query tool and reference implementation.

---

Framework Compatibility

Stateless query tool — pi-agent compatible. No daemon, no persistent state.

File	Purpose	Who reads it
SKILL.md	Skill definition, setup, usage	All agent frameworks
AGENTS.md	Dispatch guide	OpenClaw; frameworks implementing AgentSkills standard
tool.json	Machine-readable schema	OpenClaw; MCP-compatible runtimes; pi
package.json	Pi package manifest	Pi (pi install git:...)

---

Related

• skill-sms-send — send plain text SMS
• skill-mms-send — send MMS attachments
• openclaw-plugin-termux-sms — SMS channel plugin (uses this skill for polling)
• tclaw — Termux OpenClaw installer/patcher