# Whatsapp DB Skill

> Whatsapp DB Skill is an Agent Skill for apps & automation published in the zeenie-ai/OpenCompany repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Query WhatsApp database for contacts, groups, channels, and chat history. Look up contact info, search groups, manage channels, retrieve messages.

- Skill name: `whatsapp-db-skill`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/zeenie-ai/OpenCompany/blob/HEAD/server/skills/social_agent/whatsapp-db-skill/SKILL.md
- Repository: zeenie-ai/OpenCompany (323 GitHub stars when collected)

## SKILL.md

# 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.

```json
{
  "operation": "list_contacts",
  "query": "mom",
  "limit": 10
}
```

**Response:**
```json
{
  "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.

```json
{
  "operation": "get_contact_info",
  "phone": "919876543210"
}
```

**Response:**
```json
{
  "success": true,
  "operation": "get_contact_info",
  "phone": "919876543210",
  "name": "Mom",
  "jid": "919876543210@s.whatsapp.net",
  "profile_picture": "https://..."
}
```

### search_groups

Search groups by name.

```json
{
  "operation": "search_groups",
  "query": "family",
  "limit": 10
}
```

**Response:**
```json
{
  "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.

```json
{
  "operation": "get_group_info",
  "group_id": "120363123456789@g.us",
  "participant_limit": 20
}
```

**Response:**
```json
{
  "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.

```json
{
  "operation": "chat_history",
  "chat_type": "individual",
  "phone": "919876543210",
  "limit": 20
}
```

### chat_history (Group)

Get messages from a group chat.

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

**Response:**
```json
{
  "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.

```json
{
  "operation": "check_contacts",
  "phones": "1234567890,0987654321"
}
```

**Response:**
```json
{
  "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.

```json
{
  "operation": "list_channels",
  "limit": 10
}
```

**Response:**
```json
{
  "success": true,
  "operation": "list_channels",
  "channels": [
    {"jid": "120363198765432101@newsletter", "name": "Tech Updates", "subscriber_count": 5000}
  ],
  "total": 3
}
```

### get_channel_info

Get channel details.

```json
{
  "operation": "get_channel_info",
  "channel_jid": "120363198765432101@newsletter"
}
```

### channel_messages

Get channel message history.

```json
{
  "operation": "channel_messages",
  "channel_jid": "120363198765432101@newsletter",
  "channel_count": 10
}
```

### channel_follow

Follow/subscribe to a channel.

```json
{
  "operation": "channel_follow",
  "channel_jid": "120363198765432101@newsletter"
}
```

### channel_create

Create a new newsletter channel.

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

### channel_mute

Mute or unmute a newsletter channel.

```json
{
  "operation": "channel_mute",
  "channel_jid": "120363198765432101@newsletter",
  "mute": true
}
```

### channel_mark_viewed

Mark channel messages as viewed by server ID.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "operation": "channel_messages",
  "channel_jid": "120363198765432101@newsletter",
  "search": "announcement",
  "channel_count": 10
}
```

### newsletter_react

React to a channel message with an emoji.

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

### contact_profile_pic

Get a contact's profile picture.

```json
{
  "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

```json
{
  "error": "Phone number is required for chat_type='individual'"
}
```

```json
{
  "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)

---

Source: https://www.openparable.com/skill/apps-automation/whatsapp-db-skill (OpenParable). Cite the canonical URL above.
