whatsapp-db-skill

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

Operations

Limits

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

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)