Reactions

How it works

The /add-reactions skill gives your NanoClaw agent the ability to both receive and send emoji reactions on WhatsApp. Reactions are stored in SQLite, queryable by message, emoji, or user, and the agent gets an MCP tool to react to messages programmatically.

The skill applies a database migration that creates a reactions table with a composite primary key and indexes for efficient lookups. It hooks into the WhatsApp channel’s messages.reaction event to capture incoming reactions in real time — whenever someone reacts to a message in a registered chat, the reaction is stored with the message key, emoji, sender, and timestamp.

On the outbound side, the skill adds a react_to_message MCP tool to the container agent. The agent can call this tool to place an emoji reaction on any message in its own group’s chat. The IPC layer enforces group-scoped authorization — an agent running in one group cannot react to messages in another group’s chat.

Status tracking

The skill includes a StatusTracker — a forward-only emoji state machine that uses reactions for message lifecycle signaling. This lets the agent use reactions as visual status indicators. For example, a thinking emoji while processing, a checkmark when done, or an error emoji if something fails. The state machine ensures reactions only move forward (processing → complete, never backward), and includes persistence and retry logic for reliability.

What you can query

Once reactions are flowing into the database, several query functions are available:

• By message — get all reactions on a specific message
• By emoji — find all messages that received a particular reaction
• By user — see all reactions a specific person has sent
• Stats — aggregate reaction counts across your chats

These queries are available to the agent through the database module, so you can ask your agent things like “what messages did I react to with a thumbs up this week” and it can look them up.

Tips

• Reactions are lightweight — they don’t count toward WhatsApp’s message rate limits.
• The agent can only react to messages in its own group’s chat. Cross-group reactions are blocked at the IPC layer and logged as unauthorized attempts.
• If reactions aren’t appearing in the database, check that the chat is registered and that NanoClaw is connected to WhatsApp.
• The migration is idempotent — if the reactions table already exists, running the migration again is a no-op.