whatsapp-db-skill

name	whatsapp-db-skill
description	Query WhatsApp database for contacts, groups, channels, and chat history. Look up contact info, search groups, manage channels, retrieve messages.
allowed-tools	whatsapp_db
metadata	{"author":"opencompany","version":"1.0","category":"messaging"}

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

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": "[e-mail]"}
  ],
  "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": "[e-mail]",
  "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": "[e-mail]", "name": "Family Group", "participant_count": 5}
  ],
  "total": 1
}

get_group_info

Get group details with participant list.

{
  "operation": "get_group_info",
  "group_id": "[e-mail]",
  "participant_limit": 20
}

Response:

{
  "success": true,
  "operation": "get_group_info",
  "name": "Family Group",
  "jid": "[e-mail]",
  "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": "[e-mail]",
  "message_filter": "text_only",
  "limit": 50
}

Response:

{
  "success": true,
  "operation": "chat_history",
  "messages": [
    {
      "index": 1,
      "message_id": "ABC123",
      "sender": "[e-mail]",
      "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": "[e-mail]"},
    {"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

1. Use list_contacts with query to find the person
2. Get their phone number from the result
3. Use whatsapp_send tool with the phone number

Get recent messages from a contact

1. Use chat_history with chat_type="individual"
2. Set appropriate limit for desired history depth

Find and message a group

1. Use search_groups to find the group by name
2. Get the group_id from the result
3. Use whatsapp_send tool with recipient_type="group"

See who's in a group

1. Use get_group_info with the group_id
2. Set participant_limit to control output size

Guidelines

1. Phone numbers: Always use without + prefix, just digits
2. Group IDs: JID format ending in @g.us
3. Limits: Use small limits to avoid context overflow
4. Queries: Be specific to narrow results
5. Pagination: Use offset to page through chat_history
6. Channel JIDs: JID format ending in @newsletter, or pass an invite link URL
7. Invite links: channel_jid accepts both JIDs and https://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

1. Connect the WhatsApp DB node to Zeenie's input-tools handle
2. Ensure WhatsApp is connected (green status indicator in Credentials)