| Metadata | Value |
|---|---|
| Category | comms |
| Capabilities | sql |
| Website | https://www.whatsapp.com/ |
Returns shapes
Section titled “Returns shapes”conversation— fromop_get_conversationconversation[]— fromop_list_conversationsmessage— fromop_get_messagemessage[]— fromop_list_messages,op_search_messagesperson[]— fromop_list_persons
Connections
Section titled “Connections”db
Readme
Section titled “Readme”Read WhatsApp messages from the local macOS database. Read-only access to message history.
Requirements
Section titled “Requirements”- macOS only — Reads from local WhatsApp database
- WhatsApp desktop app — Must be installed and logged in
Conversation IDs
Section titled “Conversation IDs”Conversations use numeric IDs (SQLite primary keys like 880, 899). Always use the id returned by list_conversations — these are not JIDs.
Common Tasks
Section titled “Common Tasks”- Get active chats:
list_conversations(default — non-archived only) - Get archived chats:
list_conversationswitharchived: true - Get unread messages:
list_messageswithunread: true(no conversation_id needed) - Get group participants:
list_personswithconversation_idparam - Search messages:
search_messageswithqueryparam
Contact Identifiers
Section titled “Contact Identifiers”WhatsApp uses two identifier formats:
- JID:
12125551234@s.whatsapp.net(phone-based, used for DMs) - LID:
opaque_id@lid(server-assigned, newer format)
The list_persons operation resolves both formats to phone numbers when available via the contacts database.
Entity Model
Section titled “Entity Model”- person — the human, with phone number and name from contacts
- account — their WhatsApp identity (JID/LID), linked to person via
claimrelationship - conversation — a chat thread, with
participant→ account reference for the DM partner - message — a text message, with
from→ account reference for the sender
This means: person → claims → account → sends → message. Traverse the graph to connect messages to people.
is_outgoing: trueindicates messages you sent- Incoming messages include a
fromaccount reference for the sender’s WhatsApp identity - Media-only messages (images, voice notes) without text are excluded from message queries
- All timestamps are ISO 8601 format