> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencompany.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp & Social Nodes

> WhatsApp messaging and multi-platform social communication

# WhatsApp & Social Nodes

Automate WhatsApp messaging and multi-platform social communication.

## Available Nodes

| Node | Type | Purpose |
| - | - | - |
| WhatsApp Send | Action / AI Tool | Send text, media, location, contact, or sticker messages |
| WhatsApp DB | Action / AI Tool | Query chats, contacts, groups, and newsletter channels |
| WhatsApp Receive | Trigger | Wait for incoming messages |

<Info>
  WhatsApp Send and WhatsApp DB are dual-purpose: they work as standalone workflow nodes **and** as AI Agent tools when connected to an agent's tools handle.
</Info>

## Setup Requirements

1. WhatsApp service running (optional - it spawns on demand the first time you open the WhatsApp pairing panel or run a WhatsApp node)
2. WhatsApp account for pairing
3. Scan QR code to link device

### Connecting

There is no "connect" workflow node. Pairing is managed from the Credentials panel:

1. Open the **Credentials** modal and select the **WhatsApp** panel
2. Scan the displayed QR code with your WhatsApp mobile app
3. Go to WhatsApp > Settings > Linked Devices > Link a Device

***

## WhatsApp Receive

Trigger node that fires when messages arrive.

### Parameters

<ParamField path="message_type_filter" type="select" default="all">
  Filter by message type: all, text, image, video, audio, document, location, contact
</ParamField>

<ParamField path="filter" type="select" default="all">
  Sender filter mode: all, self, any\_contact, contact, group, channel, keywords
</ParamField>

<ParamField path="phone_number" type="string">
  Specific phone number, digits only, no + prefix (when filter = contact)
</ParamField>

<ParamField path="group_id" type="select">
  Specific group JID (when filter = group)
</ParamField>

<ParamField path="sender_number" type="string">
  Optional: filter group messages to a specific member (when filter = group)
</ParamField>

<ParamField path="channel_jid" type="select">
  Newsletter channel JID; leave empty to match any channel (when filter = channel)
</ParamField>

<ParamField path="keywords" type="string">
  Comma-separated keywords, case-insensitive (when filter = keywords)
</ParamField>

<ParamField path="forwarded_filter" type="select" default="all">
  Forwarded message handling: all, only\_forwarded, ignore\_forwarded
</ParamField>

<ParamField path="ignore_own_messages" type="boolean" default="true">
  Skip messages sent by yourself
</ParamField>

<ParamField path="include_media_data" type="boolean" default="false">
  Download base64 media data with the event
</ParamField>

### Filter Options

| Filter | Description |
| - | - |
| All Messages | Receive everything |
| From Self | Notes-to-self chat only |
| From Any Contact | Non-group messages only |
| From Specific Contact | Match phone number |
| From Specific Group | Match group (optionally a specific member) |
| From Channel | Match newsletter channel |
| Contains Keywords | Match keywords in message |

### Output

```json theme={null}
{
  "message_id": "ABC123",
  "sender": "1234567890@s.whatsapp.net",
  "sender_phone": "+1234567890",
  "chat_id": "1234567890@s.whatsapp.net",
  "message_type": "text",
  "text": "Hello!",
  "timestamp": "2024-01-15T10:30:00Z",
  "is_group": false,
  "is_from_me": false,
  "push_name": "John Doe",
  "is_forwarded": false,
  "forwarding_score": 0,
  "group_info": null
}
```

### Group Message Output

When `is_group` is true:

```json theme={null}
{
  "group_info": {
    "group_jid": "123456789@g.us",
    "sender_jid": "1234567890@s.whatsapp.net",
    "sender_phone": "+1234567890",
    "sender_name": "John Doe"
  }
}
```

### Example: Reply to Specific Keywords

```
Filter: Contains Keywords
Keywords: help, support, question
```

***

## WhatsApp Send

Send messages to yourself, individual contacts, groups, or newsletter channels. Works as a workflow node or an AI Agent tool.

### Parameters

<ParamField path="recipient_type" type="select" default="self">
  Where to send: self (connected phone), phone (individual), group, or channel (newsletter)
</ParamField>

<ParamField path="phone" type="string">
  Recipient phone number, digits only, no + prefix (when recipient\_type = phone)
</ParamField>

<ParamField path="group_id" type="select">
  Group JID, format [123456789@g.us](mailto:123456789@g.us) (when recipient\_type = group)
</ParamField>

<ParamField path="channel_jid" type="select">
  Newsletter channel JID, format 120363...\@newsletter; admin/owner role required (when recipient\_type = channel)
</ParamField>

<ParamField path="message_type" type="select" default="text">
  Type of message: text, image, video, audio, document, sticker, location, contact. Channels only support text, image, video, audio, document.
</ParamField>

<ParamField path="message" type="string">
  Text content (when message\_type = text). Supports template variables.
</ParamField>

<ParamField path="format_markdown" type="boolean" default="true">
  Convert markdown (bold, italic, code, lists) to WhatsApp-native formatting (when message\_type = text)
</ParamField>

<ParamField path="media_source" type="select" default="base64">
  Source of media data: base64, file, or url (for image / video / audio / document / sticker)
</ParamField>

<ParamField path="media_url" type="string">
  HTTPS URL to download media from (when media\_source = url)
</ParamField>

<ParamField path="caption" type="string">
  Optional caption for image, video, or document
</ParamField>

<Tip>
  Location messages use `latitude` / `longitude` / `location_name` / `address`. Contact messages use `contact_name` / `vcard`. Quote a message with `is_reply` + `reply_message_id`.
</Tip>

### Output

```json theme={null}
{
  "message_id": "XYZ789",
  "sent": true
}
```

### Example: Auto-Reply

```
Recipient Type: phone
Phone: {{whatsappReceive.sender_phone}}
Message: Thanks for your message! I'll get back to you soon.
```

### Example: Forward to Admin

```
Recipient Type: phone
Phone: 1987654321
Message: New message from {{whatsappReceive.push_name}}: {{whatsappReceive.text}}
```

***

## WhatsApp DB

Query the WhatsApp database: chat history, contacts, groups, and newsletter channels. Works as a workflow node or an AI Agent tool.

### Parameters

<ParamField path="operation" type="select" default="chat_history">
  Operation to perform (see table below)
</ParamField>

The remaining fields depend on the selected operation (e.g. `phone`, `group_id`, `query`, `channel_jid`, `limit`, `offset`, `include_media_data`).

### Operations

| Operation | Purpose |
| - | - |
| `chat_history` | Retrieve messages from an individual or group chat (with pagination and optional media download) |
| `search_groups` | Search groups by name |
| `get_group_info` | Get group details with participant names and phone numbers |
| `get_contact_info` | Get full contact info (name, phone, profile picture) |
| `list_contacts` | List all contacts with saved names |
| `check_contacts` | Check WhatsApp registration status for phone numbers |
| `list_channels` | List subscribed newsletter channels |
| `get_channel_info` | Get channel details (name, description, subscribers) |
| `channel_messages` | Get channel message history with filters and pagination |
| `channel_stats` | Get channel subscriber/view statistics |
| `channel_follow` / `channel_unfollow` | Follow or unfollow a newsletter channel |
| `channel_create` | Create a new newsletter channel |
| `channel_mute` | Mute or unmute a channel |
| `channel_mark_viewed` | Mark channel messages as viewed |
| `newsletter_react` | React to a channel message with an emoji |
| `newsletter_live_updates` | Subscribe to live view/reaction counts |
| `contact_profile_pic` | Get profile picture for a contact or group |

### Example: Look Up a Contact

```
Operation: get_contact_info
Contact Phone: 1234567890
```

***

## Common Workflows

### Auto-Responder

```
[WhatsApp Receive] --> [AI Agent] --> [WhatsApp Send]
```

**AI Agent Prompt:**

```
Respond to this customer message: {{whatsappReceive.text}}
Be helpful and professional.
```

**Send Config:**

```
Recipient Type: phone
Phone: {{whatsappReceive.sender_phone}}
Message: {{aiAgent.response}}
```

### Group Monitor

```
[WhatsApp Receive] --> [Python Executor] --> [Webhook/Database]
     (group filter)        (log message)
```

**Filter Config:**

```
Filter: From Specific Group
Group: [Select your group]
```

### Keyword Bot

```
[WhatsApp Receive] --> [Python Executor] --> [WhatsApp Send]
   (keywords: help)      (select response)
```

**Python Code:**

```python theme={null}
text = input_data.get("text", "").lower()

if "hours" in text:
    response = "We're open 9am-5pm, Mon-Fri"
elif "price" in text:
    response = "Please visit our website for pricing"
else:
    response = "How can I help you?"

output = {"response": response}
```

***

## Tips

<Tip>
  Use `{{whatsappReceive.sender_phone}}` to reply to the sender automatically.
</Tip>

<Tip>
  Combine with **Simple Memory** for context-aware conversations per contact.
</Tip>

<Tip>
  Set `Session ID: {{whatsappReceive.sender_phone}}` in Simple Memory for per-user history.
</Tip>

<Warning>
  Respect WhatsApp's terms of service. Don't send spam or bulk unsolicited messages.
</Warning>

***

## Troubleshooting

<Accordion title="QR code not appearing">
  The WhatsApp service (whatsapp-rpc) is optional and spawns on demand — opening
  the pairing panel starts it (port 5683). If the QR code doesn't appear, close
  and reopen the pairing panel; as a last resort restart:

  ```bash theme={null}
  company stop
  company start
  ```
</Accordion>

<Accordion title="Messages not received">
  * Verify workflow is **deployed** (not just saved)
  * Check filter settings aren't too restrictive
  * Confirm `ignoreOwnMessages` setting
</Accordion>

<Accordion title="Send fails">
  * Include country code in phone number
  * Check WhatsApp connection status
  * Verify recipient hasn't blocked you
</Accordion>

<Accordion title="Connection drops frequently">
  * Check internet connectivity
  * Ensure phone stays online
  * Don't use WhatsApp Web simultaneously
</Accordion>

***

## Social Nodes

Unified messaging nodes for multi-platform communication. Social Send currently routes to WhatsApp (personal and Business) and Discord; the other platforms it lists are not yet wired. Social Receive normalizes messages from any connected platform trigger.

### Social Receive

Normalizes messages from any platform trigger into a unified format.

**Output Fields:**

* `channel` - Platform name
* `message_id`, `sender_id`, `sender_name`
* `text`, `message_type`, `timestamp`
* `media` - Platform-specific media data

### Social Send (Dual-Purpose)

Send messages to any supported platform. Works as workflow node OR AI Agent tool.

**Message Types:** text, image, video, audio, document, sticker, location, contact, poll, buttons, list

```
[Social Receive] --> [AI Agent] --> [Social Send]
                          ^
                          |
                    [Social Send as Tool]
```

***

## Related

<CardGroup cols={2}>
  <Card title="WhatsApp Tutorial" icon="whatsapp" href="/tutorials/whatsapp-automation">
    Step-by-step guide
  </Card>

  <Card title="AI Agent" icon="robot" href="/nodes/ai-agent">
    Add AI-powered responses
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.