Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chamilonster/Piumy/llms.txt

Use this file to discover all available pages before exploring further.

These tools handle the message flow — reading inbound messages, pulling the advanced-mode queue, sending replies through the anti-ban governor, and marking work done. The most critical tool here is send_message, which has several mandatory gates that must be satisfied before a message is queued.

​
get_messages

Returns recent messages from a chat.
​
chat_id
string
required
Chat JID.
​
limit
number
default:"20"
Maximum number of messages to return.
Returns an array of message objects from the chat’s history.
Retrieving messages via this tool is what marks inbound messages as read on WhatsApp. This is intentional — reads reflect real attention, not just the gateway having received them. The read receipt is sent with an anti-ban delay and is never instant. Do not call this tool in a tight loop expecting instant delivery confirmation.

​
get_queue

Returns incoming messages in advanced mode that are waiting for an agent to handle them.
​
limit
number
default:"20"
Maximum number of queued messages to return.
Returns an array of pending advanced-mode messages. Calling this tool also refreshes the queue count in get_status.

​
get_decision_policy

Returns the agent’s decision policy — the set of rules that governs whether and how to reply to any chat. You must call this before every send_message call. No parameters. Returns:
FieldDescription
policyThe full policy text (plain text, owner-editable without restart)
policy_versionA SHA-256 hash of the current policy content
The policy_version value must be passed verbatim to send_message. If the owner has edited the policy since you last called get_decision_policy, the version hash will have changed and send_message will reject your call with "stale/missing policy_version — call get_decision_policy first".
Always call get_decision_policy immediately before send_message — even if you called it 30 seconds ago. The owner can edit the policy at any time without restarting the service, and a stale hash is an immediate rejection. There is no grace period.

​
send_message

Queues a message to send over WhatsApp. The anti-ban governor dispatches it with human-paced timing — it is not sent instantly.
​
to
string
required
Destination JID (e.g. 56999999999@s.whatsapp.net). Must be a full JID with @, not a bare phone number. Copy it from list_chats, get_queue, or resolve_chat — do not construct it by hand.
​
message
string
required
The text content to send.
​
model
string
required
The agent’s identity string. Every reply is attributed to this value, and it is checked against any active claim_chat lock on the destination chat.
​
policy_version
string
required
The exact policy_version hash returned by get_decision_policy. Must match the current policy — call get_decision_policy first, every time.
Returns "queued for sending" on success.

​
send_message gates

Every call passes through a chain of checks, in order. All rejections return a clear error string — never a silent drop.
All eight gates must pass before a message is queued. A failure at any gate returns an error and the message is not enqueued.
  1. Muted check — If get_status shows muted: true, send_message returns "muted: message not sent". Stop — do not loop or retry. The mute is the owner’s kill switch.
  2. Policy version check — policy_version must exactly match the current hash from get_decision_policy. Stale or missing → rejected.
  3. JID format check — to must contain @. A bare number (e.g. 56999999999) is rejected with a message telling you to copy the JID from list_chats / get_queue / resolve_chat.
  4. Chat existence check — The chat must exist in the store. If GetChat finds no record for the destination JID, the call is rejected with "error: no rules on this chat".
  5. Claim check — If another model holds an unexpired claim_chat lock on this chat, the call is rejected with who holds it and until when.
  6. Effective rules check — The chat must have effective rules (particular → type → global default). A chat with no rules at any tier is rejected with "error: no rules on this chat". Rules are set by the owner only, never over MCP.
  7. Group status check — If the destination is a WhatsApp group (@g.us) and its status is "ignored", the call is rejected. The owner must explicitly un-ignore the group first.
  8. Router whitelist check — The JID must be in the router whitelist. Rejected with "refusing to send: <jid> is not in the whitelist (anti-ban)".

​
Example tool call

{
  "tool": "send_message",
  "arguments": {
    "to": "56999999999@s.whatsapp.net",
    "message": "Hola! Claro, te lo confirmo a la brevedad.",
    "model": "claude-opus-4-5",
    "policy_version": "a3f8d2e1c7b049..."
  }
}
The typical sequence is: 
get_decision_policy  →  (read policy, save policy_version)
get_chat             →  (confirm rules are set, check claimed_by)
send_message         →  (pass policy_version, model, full JID)
mark_handled         →  (for advanced-mode queue entries)

​
set_mode

Changes a chat’s mode.
​
chat_id
string
required
Chat JID.
​
mode
string
required
auto — the auto-reply API handles this chat, or advanced — an agent handles it over MCP.
Returns "mode updated to <mode>" on success. Also refreshes the queue count.

​
escalate

Escalates a chat to advanced mode so a more capable agent or a human operator can take it. Use this whenever you’re uncertain — when in doubt, escalate rather than guessing.
​
chat_id
string
required
Chat JID.
Returns "escalated to advanced" on success.
escalate is a specialized shortcut for set_mode with mode=advanced. It also triggers the thinking mood on the e-paper display (a visual cue that a handoff is happening) and refreshes the queue count.

​
mark_handled

Marks a queued advanced-mode message as handled. Call this after you have sent a reply (or decided not to reply) to a specific queue entry.
​
chat_id
string
required
Chat JID.
​
message_id
string
required
Message ID from the queue entry (returned by get_queue).
Returns "ok" on success. Also triggers the done mood on the e-paper face and refreshes the queue count.

​
get_outbox

Returns messages that have been queued via send_message but have not yet been dispatched by the gateway.
​
limit
number
default:"20"
Maximum number of outbox entries to return.
Returns an array of pending outbox items.
send_message always returns "queued for sending" — it cannot tell you whether the gateway has actually delivered the message. Use get_outbox to check if a reply is still waiting to be sent (e.g. if the gateway is disconnected or the JID was malformed).

​
get_media

Returns images, videos, and stickers that have been downloaded from a chat, with their file paths on disk, MIME type, and file size.
​
chat_id
string
required
Chat JID.
​
limit
number
default:"20"
Maximum number of media entries to return.
Returns an array of media records with file path, MIME type, and size.

​
get_drafts

Returns pending auto-reply drafts that are awaiting the owner’s approval before being sent.
​
limit
number
default:"20"
Maximum number of draft entries to return.
Returns an array of pending draft records.
get_drafts is read-only over MCP. Approving or discarding a draft requires the privileged dashboard or REST API (/api/drafts/approve and /api/drafts/discard). An agent can see what the auto-reply worker has drafted, but cannot approve it.

Build docs developers (and LLMs) love

Get started for freeTalk to us