tomevault-io WhatsApp Database Tool
Query WhatsApp database for contacts, groups, channels (newsletters), and message history.
How It Works
This skill provides instructions for the WhatsApp DB tool node. Connect the WhatsApp DB node to Zeenie's input-tools handle to enable database queries.
whatsapp_db Tool
Query contacts, groups, channels, and chat history.
Schema Fields
| Field | Type | Required | Description |
|---|---|---|---|
| operation | string | Yes | Operation type (see below) |
| chat_type | string | For chat_history | "individual" or "group" |
| phone | string | Varies | Phone number (for chat_history individual, get_contact_info) |
| group_id | string | Varies | Group JID (for chat_history group, get_group_info) |
| query | string | No | Search query (for search_groups, list_contacts) |
| limit | int | No | Max results (varies by operation) |
| offset | int | No | Pagination offset (for chat_history) |
| message_filter | string | No | "all" or "text_only" (for chat_history) |
| group_filter | string | No | "all" or "contact" (for group chat_history) |
| sender_phone | string | No | Filter by sender (when group_filter="contact") |
| phones | string | For check_contacts | Comma-separated phone numbers |
| participant_limit | int | No | Max participants (for get_group_info, 1-100) |
| channel_jid | string | For channel ops | Newsletter JID or invite link URL (e.g., 120363198765432101@newsletter or https://whatsapp.com/channel/...) |
| refresh | boolean | No | Force refresh from server (for list_channels, get_channel_info, channel_messages) |
| channel_count | int | No | Number of items to fetch (for channel_messages, channel_stats) |
| before_server_id | int | No | Pagination cursor (for channel_messages) |
| message_offset | int | No | Skip this many messages (for channel_messages) |
| since | string | No | Unix timestamp - messages after this time (for channel_messages) |
| until | string | No | Unix timestamp - messages before this time (for channel_messages) |
| media_type | string | No | Filter by media type: image, video, audio, document, sticker (for channel_messages) |
| search | string | No | Text search within messages (for channel_messages) |
| include_media_data | boolean | No | Download base64 media data for media messages (for chat_history, channel_messages) |
| channel_name | string | For channel_create | Name of the new channel |
| channel_description | string | No | Description (for channel_create) |
| picture | string | No | Base64-encoded profile picture (for channel_create) |
| mute | boolean | For channel_mute | True to mute, false to unmute |
| server_ids | string | For mark_viewed/live_updates | Comma-separated message server IDs |
| react_server_id | int | For newsletter_react | Server ID of message to react to |
| reaction | string | For newsletter_react | Reaction emoji (empty to remove) |
| profile_pic_jid | string | For contact_profile_pic | JID or phone number |
| preview | boolean | No | Get low-res preview (for contact_profile_pic) |
Operations
| Operation | Description | Required Fields |
|---|---|---|
list_contacts |
List contacts with saved names | query (optional), limit |
get_contact_info |
Get full contact details | phone |
search_groups |
Search groups by name | query, limit |
get_group_info |
Get group details with participants | group_id |
chat_history |
Retrieve message history | chat_type, phone/group_id |
check_contacts |
Check WhatsApp registration | phones |
list_channels |
List subscribed newsletter channels | refresh (optional), limit |
get_channel_info |
Get channel details | channel_jid |
channel_messages |
Get channel messages with filters (date, media type, search) | channel_jid, channel_count |
channel_stats |
Get channel subscriber/view stats | channel_jid |
channel_follow |
Follow/subscribe to a channel | channel_jid |
channel_unfollow |
Unfollow/unsubscribe from a channel | channel_jid |
channel_create |
Create a new newsletter channel | channel_name |
channel_mute |
Mute or unmute a channel | channel_jid, mute |
channel_mark_viewed |
Mark channel messages as viewed | channel_jid, server_ids |
newsletter_react |
React to a channel message | channel_jid, react_server_id, reaction |
newsletter_live_updates |
Subscribe to live view/reaction counts | channel_jid, server_ids |
contact_profile_pic |
Get contact/group profile picture | profile_pic_jid |
Limits
| Operation | Default | Max |
|---|---|---|
| chat_history | 50 | 500 |
| search_groups | 20 | 50 |
| list_contacts | 50 | 100 |
| get_group_info participants | 50 | 100 |
| list_channels | 20 | 50 |
| channel_messages | 20 | 100 |
| channel_stats | 10 | 100 |
| channel_mute | - | - |
| channel_mark_viewed | - | - |
Important: Always use small limits and specific queries to avoid context overflow.
Operation Examples
list_contacts
Find contacts by name.
{
"operation": "list_contacts",
"query": "mom",
"limit": 10
}
Response:
{
"success": true,
"operation": "list_contacts",
"contacts": [
{"phone": "919876543210", "name": "Mom", "jid": "919876543210@s.whatsapp.net"}
],
"total": 1
}
get_contact_info
Get full contact details for sending/replying.
{
"operation": "get_contact_info",
"phone": "919876543210"
}
Response:
{
"success": true,
"operation": "get_contact_info",
"phone": "919876543210",
"name": "Mom",
"jid": "919876543210@s.whatsapp.net",
"profile_picture": "https://..."
}
search_groups
Search groups by name.
{
"operation": "search_groups",
"query": "family",
"limit": 10
}
Response:
{
"success": true,
"operation": "search_groups",
"groups": [
{"group_id": "120363123456789@g.us", "name": "Family Group", "participant_count": 5}
],
"total": 1
}
get_group_info
Get group details with participant list.
{
"operation": "get_group_info",
"group_id": "120363123456789@g.us",
"participant_limit": 20
}
Response:
{
"success": true,
"operation": "get_group_info",
"name": "Family Group",
"jid": "120363123456789@g.us",
"participants": [
{"phone": "919876543210", "name": "Mom", "is_admin": true},
{"phone": "919876543211", "name": "Dad", "is_admin": false}
],
"total_participants": 5
}
chat_history (Individual)
Get messages from an individual chat.
{
"operation": "chat_history",
"chat_type": "individual",
"phone": "919876543210",
"limit": 20
}
chat_history (Group)
Get messages from a group chat.
{
"operation": "chat_history",
"chat_type": "group",
"group_id": "120363123456789@g.us",
"message_filter": "text_only",
"limit": 50
}
Response:
{
"success": true,
"operation": "chat_history",
"messages": [
{
"index": 1,
"message_id": "ABC123",
"sender": "919876543210@s.whatsapp.net",
"sender_name": "Mom",
"text": "Hello!",
"timestamp": "2025-01-30T12:00:00",
"is_from_me": false
}
],
"total": 50,
"has_more": true
}
check_contacts
Check if phone numbers have WhatsApp.
{
"operation": "check_contacts",
"phones": "1234567890,0987654321"
}
Response:
{
"success": true,
"operation": "check_contacts",
"results": [
{"phone": "1234567890", "registered": true, "jid": "1234567890@s.whatsapp.net"},
{"phone": "0987654321", "registered": false}
]
}
list_channels
List subscribed newsletter channels.
{
"operation": "list_channels",
"limit": 10
}
Response:
{
"success": true,
"operation": "list_channels",
"channels": [
{"jid": "120363198765432101@newsletter", "name": "Tech Updates", "subscriber_count": 5000}
],
"total": 3
}
get_channel_info
Get channel details.
{
"operation": "get_channel_info",
"channel_jid": "120363198765432101@newsletter"
}
channel_messages
Get channel message history.
{
"operation": "channel_messages",
"channel_jid": "120363198765432101@newsletter",
"channel_count": 10
}
channel_follow
Follow/subscribe to a channel.
{
"operation": "channel_follow",
"channel_jid": "120363198765432101@newsletter"
}
channel_create
Create a new newsletter channel.
{
"operation": "channel_create",
"channel_name": "My Channel",
"channel_description": "A channel about interesting topics"
}
channel_mute
Mute or unmute a newsletter channel.
{
"operation": "channel_mute",
"channel_jid": "120363198765432101@newsletter",
"mute": true
}
channel_mark_viewed
Mark channel messages as viewed by server ID.
{
"operation": "channel_mark_viewed",
"channel_jid": "120363198765432101@newsletter",
"server_ids": "100, 101, 102"
}
get_channel_info (with invite link)
Get channel details using an invite link instead of JID.
{
"operation": "get_channel_info",
"channel_jid": "https://whatsapp.com/channel/0029Va12345abcdef"
}
channel_messages (with filters)
Get channel messages filtered by media type and date range.
{
"operation": "channel_messages",
"channel_jid": "120363198765432101@newsletter",
"channel_count": 20,
"media_type": "image",
"since": "1704067200",
"include_media_data": true
}
channel_messages (text search)
Search channel messages by text content.
{
"operation": "channel_messages",
"channel_jid": "120363198765432101@newsletter",
"search": "announcement",
"channel_count": 10
}
newsletter_react
React to a channel message with an emoji.
{
"operation": "newsletter_react",
"channel_jid": "120363198765432101@newsletter",
"react_server_id": 42,
"reaction": "\ud83d\udc4d"
}
contact_profile_pic
Get a contact's profile picture.
{
"operation": "contact_profile_pic",
"profile_pic_jid": "919876543210"
}
Common Workflows
Find and message someone by name
- Use
list_contactswith query to find the person - Get their phone number from the result
- Use
whatsapp_sendtool with the phone number
Get recent messages from a contact
- Use
chat_historywith chat_type="individual" - Set appropriate limit for desired history depth
Find and message a group
- Use
search_groupsto find the group by name - Get the group_id from the result
- Use
whatsapp_sendtool with recipient_type="group"
See who's in a group
- Use
get_group_infowith the group_id - Set participant_limit to control output size
Guidelines
- Phone numbers: Always use without + prefix, just digits
- Group IDs: JID format ending in
@g.us - Limits: Use small limits to avoid context overflow
- Queries: Be specific to narrow results
- Pagination: Use offset to page through chat_history
- Channel JIDs: JID format ending in
@newsletter, or pass an invite link URL - Invite links:
channel_jidaccepts both JIDs andhttps://whatsapp.com/channel/...URLs
Error Responses
{
"error": "Phone number is required for chat_type='individual'"
}
{
"error": "group_id is required for get_group_info"
}
Setup Requirements
- Connect the WhatsApp DB node to Zeenie's
input-toolshandle - Ensure WhatsApp is connected (green status indicator in Credentials)
Converted and distributed by TomeVault — claim your Tome and manage your conversions.