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

> Send and receive WhatsApp messages automatically

# WhatsApp Automation

Automate WhatsApp messaging with OpenCompany. Receive messages, process them, and send responses.

## Prerequisites

<Info>
  **Takes:** \~15 minutes. **You need:** OpenCompany running, one AI key ([Add your AI key](/add-api-keys)), a WhatsApp account on your phone, and npm available (the WhatsApp bridge installs itself on first use). Pairing uses one of your WhatsApp "linked devices" slots and drops if the service stops.
</Info>

<Tip>
  Want a simpler first messaging bot? The [Telegram tutorial](/tutorials/telegram-bot) needs only a free token — no phone pairing.
</Tip>

## Understanding WhatsApp Nodes

| Node | Purpose |
| - | - |
| **WhatsApp Receive** | Trigger on incoming messages |
| **WhatsApp Send** | Send messages to contacts, groups, or channels (also usable as an AI Agent tool) |
| **WhatsApp DB** | Query chat history, contacts, groups, and newsletter channels |

<Info>
  Connecting your WhatsApp account is done through the Credentials modal (WhatsApp panel), not a workflow node.
</Info>

## Step 1: Connect WhatsApp

1. Click the **WhatsApp icon** in the toolbar to open the WhatsApp panel
2. A modal appears with a QR code
3. Open WhatsApp on your phone > Settings > Linked Devices > Link a Device
4. Scan the QR code
5. Wait for "Connected" status

<Warning>
  Keep the WhatsApp service running. If it stops, you'll need to re-scan the QR code.
</Warning>

## Step 2: Create a Message Responder

Let's build a workflow that auto-replies to incoming messages.

### Add WhatsApp Receive Trigger

1. Drag **WhatsApp Receive** from the WhatsApp category
2. Configure the trigger:

```
Message Type Filter: All Messages
Sender Filter: All Messages
Ignore Own Messages: true
```

### Filter Options

| Filter | Description |
| - | - |
| All Messages | Receive everything |
| From Any Contact | Non-group messages only |
| From Specific Contact | Filter by phone number |
| From Specific Group | Filter by group |
| Contains Keywords | Match specific words |

## Step 3: Add an AI Response

1. Drag **AI Agent** from the **AI Agents** palette section onto the canvas
2. Connect WhatsApp Receive's output to the AI Agent's main input (top-left handle)
3. Click the agent and configure:

```
Provider: your provider (for example openai)
Model: pick from the dropdown
Prompt: Reply helpfully to this WhatsApp message: {{whatsappReceive.text}}
```

<Note>
  Model dropdown empty? Add your provider key first — key icon (**API Credentials**) in the toolbar.
</Note>

## Step 4: Send the Response

1. Drag **WhatsApp Send** onto the canvas
2. Connect the AI Agent's output to WhatsApp Send's input
3. Configure:

```
Phone Number: {{whatsappReceive.sender_phone}}
Message: {{aiAgent.response}}
```

## Complete Workflow

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

## Step 5: Start it

1. Press the green **Start** button in the top toolbar
2. Send a message to your linked WhatsApp number from another phone
3. The workflow triggers and sends an AI response

## Available Data from WhatsApp Receive

| Field | Type | Description |
| - | - | - |
| `message_id` | string | Unique message ID |
| `sender` | string | Sender JID |
| `sender_phone` | string | Phone number |
| `chat_id` | string | Chat/group ID |
| `message_type` | string | text, image, video, etc. |
| `text` | string | Message content |
| `timestamp` | string | When message was sent |
| `is_group` | boolean | True if from a group |
| `is_from_me` | boolean | True if sent by you |
| `push_name` | string | Sender's display name |
| `is_forwarded` | boolean | True if forwarded |
| `group_info` | object | Group details (if group message) |

## Group Message Handling

For group messages, use:

```
{{whatsappReceive.group_info.group_jid}}
{{whatsappReceive.group_info.sender_name}}
{{whatsappReceive.group_info.sender_phone}}
```

## Example: Keyword-Based Response

Set up different responses based on keywords:

### Configuration

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

### AI Prompt

```
The user needs help. Their message: {{whatsappReceive.text}}
Provide a helpful response.
```

## Example: Group Bot

Reply only in specific groups:

```
Sender Filter: From Specific Group
Group: [Select from dropdown]
```

## Troubleshooting

<Accordion title="QR code not appearing">
  * Ensure the WhatsApp service is running (default port 5683)
  * Open the WhatsApp panel from the toolbar and click **Restart** to relaunch the connection
  * Check the Terminal tab for WhatsApp service logs
</Accordion>

<Accordion title="Messages not being received">
  * Verify the workflow is started (**Start** pressed, not just saved)
  * Check "Ignore Own Messages" setting
  * Ensure filters aren't too restrictive
</Accordion>

<Accordion title="Send fails with error">
  * Verify phone number format (include country code)
  * Check WhatsApp connection status
  * Ensure recipient hasn't blocked you
</Accordion>

## Tips

<Tip>
  Use **Simple Memory** with WhatsApp for context-aware conversations. Set Session ID to `{{whatsappReceive.sender_phone}}` for per-contact memory.
</Tip>

<Tip>
  Test with your own number first before deploying to production.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Android Automation" icon="mobile" href="/tutorials/android-automation">
    Control Android devices
  </Card>

  <Card title="WhatsApp Node Reference" icon="book" href="/nodes/whatsapp">
    Full node documentation
  </Card>
</CardGroup>


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