chats
Read, search, and manage WhatsApp conversations: list threads, fetch messages and media, send text/media/polls, mark read, archive, and load older history.
Instructions
Read or send WhatsApp messages inside chats on the connected engine. Available actions:
list: list chats, newest message first (offset pagination via limit/skip)
search: list chats matching a name/keyword query. Archived chats are excluded by default — pass include_archive=true to find an archived chat (e.g. to get its chat_id before unarchive).
get: retrieve a single chat by chat_id (e.g. 972544325389@c.us)
list_messages: list messages inside a chat
mark_read: mark all messages in a chat as read
archive: archive a chat (hide it from the main chat list)
unarchive: unarchive a chat (restore it to the main chat list)
get_media: download media bytes for one message by its wire key — returns url/data_base64 + mimetype/filename + original_quality flag (false when WA returned a preview rather than the original; currently only happens for own-sent newsletter media).
get_participants: list the members of a group chat
load_more_history: request OLDER history for ONE specific chat (chat_id) from the phone, so a subsequent list_messages can page further back. Each call pulls one page; call it again to go deeper. Use it whenever a chat's loaded messages don't reach far enough back for what you need. Paced and limited: one request per chat at a time, WA-paced — a call while that chat's request is in flight or cooling down returns added:0 (not an error); wait and retry. While the initial sync is still running the call throws a not_connected error. After repeated unanswered requests WhatsApp history requests pause: the result's
errorstarts "cooling_down:" and says how long to wait — retry after that, don't treat it as "no history". canLoadMore:false = history is genuinely exhausted — stop paging. A chat with no messages AND no chat activity on the engine (e.g. a saved contact whose conversation WhatsApp's first sync never delivered:getreturns it with lastMessageAt null) has nothing to page back from, so added stays 0. Once one message is sent or received in that chat, its older history can be requested.send_message_text: send a text message NOW (fire-and-forget). Body: {chat_id, type: "text", text}
send_message_media: send an image/video/audio/document NOW. Body: {chat_id, type: "media", media: {url, kind?, caption?, filename?}}
send_message_poll: send a poll NOW. Body: {chat_id, type: "poll", poll: {question, options[2..12], allow_multiple?}}
type is derived automatically from the action ("text"/"media"/"poll"),
so you don't need to send it; include it only if you want to be explicit.
send_message_* is for IMMEDIATE delivery into a chat — use the
scheduled_messages tool's send action to schedule a future send (with
send_at) or to keep the message in a queue you can edit/cancel before
dispatch.
Examples:
list: 'show me my recent chats'
search: 'find chats with noam'
list_messages: 'last 20 messages with 972544325389@c.us'
send_message_text: 'reply hi to 972544325389@c.us'
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | ||
| poll | No | ||
| skip | No | ||
| text | No | ||
| type | No | ||
| limit | No | ||
| media | No | ||
| order | No | ||
| query | No | ||
| since | No | ||
| until | No | ||
| action | Yes | ||
| chat_id | No | ||
| reply_to | No | ||
| message_types | No | ||
| include_archive | No |