> ## 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 (starts automatically with `machina start`)
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] --> [OpenAI Chat] --> [WhatsApp Send]
```

**AI Prompt:**

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

**Send Config:**

```
Recipient Type: phone
Phone: {{whatsappReceive.sender_phone}}
Message: {{openaiChatModel.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) starts automatically with `machina start`
  and listens on port 9400. Restart all services if the QR code doesn't appear:

  ```bash theme={null}
  npx machina stop
  npx machina 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. Supports WhatsApp, Telegram, Discord, Slack, Signal, SMS, Webchat, Email, Matrix, Teams.

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