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.

jsonCopy code
{
  "operation": "list_contacts",
  "query": "mom",
  "limit": 10
}

Response:

jsonCopy code
{
  "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.

jsonCopy code
{
  "operation": "get_contact_info",
  "phone": "919876543210"
}

Response:

jsonCopy code
{
  "success": true,
  "operation": "get_contact_info",
  "phone": "919876543210",
  "name": "Mom",
  "jid": "919876543210@s.whatsapp.net",
  "profile_picture": "https://..."
}

search_groups

Search groups by name.

jsonCopy code
{
  "operation": "search_groups",
  "query": "family",
  "limit": 10
}

Response:

jsonCopy code
{
  "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.

jsonCopy code
{
  "operation": "get_group_info",
  "group_id": "120363123456789@g.us",
  "participant_limit": 20
}

Response:

jsonCopy code
{
  "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.

jsonCopy code
{
  "operation": "chat_history",
  "chat_type": "individual",
  "phone": "919876543210",
  "limit": 20
}

chat_history (Group)

Get messages from a group chat.

jsonCopy code
{
  "operation": "chat_history",
  "chat_type": "group",
  "group_id": "120363123456789@g.us",
  "message_filter": "text_only",
  "limit": 50
}

Response:

jsonCopy code
{
  "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.

jsonCopy code
{
  "operation": "check_contacts",
  "phones": "1234567890,0987654321"
}

Response:

jsonCopy code
{
  "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.

jsonCopy code
{
  "operation": "list_channels",
  "limit": 10
}

Response:

jsonCopy code
{
  "success": true,
  "operation": "list_channels",
  "channels": [
    {"jid": "120363198765432101@newsletter", "name": "Tech Updates", "subscriber_count": 5000}
  ],
  "total": 3
}

get_channel_info

Get channel details.

jsonCopy code
{
  "operation": "get_channel_info",
  "channel_jid": "120363198765432101@newsletter"
}

channel_messages

Get channel message history.

jsonCopy code
{
  "operation": "channel_messages",
  "channel_jid": "120363198765432101@newsletter",
  "channel_count": 10
}

channel_follow

Follow/subscribe to a channel.

jsonCopy code
{
  "operation": "channel_follow",
  "channel_jid": "120363198765432101@newsletter"
}

channel_create

Create a new newsletter channel.

jsonCopy code
{
  "operation": "channel_create",
  "channel_name": "My Channel",
  "channel_description": "A channel about interesting topics"
}

channel_mute

Mute or unmute a newsletter channel.

jsonCopy code
{
  "operation": "channel_mute",
  "channel_jid": "120363198765432101@newsletter",
  "mute": true
}

channel_mark_viewed

Mark channel messages as viewed by server ID.

jsonCopy code
{
  "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.

jsonCopy code
{
  "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.

jsonCopy code
{
  "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.

jsonCopy code
{
  "operation": "channel_messages",
  "channel_jid": "120363198765432101@newsletter",
  "search": "announcement",
  "channel_count": 10
}

newsletter_react

React to a channel message with an emoji.

jsonCopy code
{
  "operation": "newsletter_react",
  "channel_jid": "120363198765432101@newsletter",
  "react_server_id": 42,
  "reaction": "\ud83d\udc4d"
}

contact_profile_pic

Get a contact's profile picture.

jsonCopy code
{
  "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

jsonCopy code
{
  "error": "Phone number is required for chat_type='individual'"
}

jsonCopy code
{
  "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)