🔗 n8n Integration Tutorial

Learn how to integrate Whinself with n8n to create powerful WhatsApp automation workflows. This tutorial shows you how to set up a local development environment where Whinself forwards incoming WhatsApp messages to n8n webhooks and enables automated responses.

What You'll Build

By the end of this tutorial, you'll have:

• A local stack with n8n running on http://localhost:5678 and Whinself on http://localhost:8888
• Whinself configured to forward all incoming WhatsApp messages to an n8n webhook
• An n8n workflow that can automatically reply to WhatsApp messages
• A complete automation pipeline for WhatsApp message handling

Prerequisites

Before you begin, ensure you have:

• Docker Desktop with Docker Compose installed
• Ports 5678 (n8n) and 8888 (Whinself) available on your machine
• Internet access for WhatsApp Web QR code scanning
• Basic understanding of Docker and webhooks

Step 1: Create Docker Compose Configuration

Create a docker-compose.yml file in your project directory with the following configuration:

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - TZ=Europe/Madrid
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=admin
      - N8N_HOST=n8n
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - WEBHOOK_URL=http://localhost:5678/
      # Strongly recommended: use a long, random key
      - N8N_ENCRYPTION_KEY=CHANGE_THIS_TO_A_LONG_RANDOM_VALUE
    volumes:
      - n8n_data:/home/node/.n8n

  whinself:
    image: inutil/whingo:latest
    container_name: whinself
    restart: unless-stopped
    ports:
      - "8888:8888" # must match PORTIN
    environment:
      - PORTIN=8888
      # Whinself will POST all incoming messages here (internal service name 'n8n')
      - NRURL=http://n8n:5678/webhook/whinself-incoming
      - SLOTID=my-bot
      - DEVICENAME=whinself
      - DEBUGLEVEL=2
      - LOGSTDOUT=true
      - LOGSSE=true # live logs via /events/logs
    depends_on:
      - n8n

volumes:
  n8n_data:

Important: If you change ports, update both the port mapping and the related environment variables accordingly.

Step 2: Start the Services

From the folder containing your docker-compose.yml, start the services in detached mode:

docker compose up -d

Useful Commands

# Check service status
docker compose ps

# View logs
docker compose logs -f whinself
docker compose logs -f n8n

# Restart services
docker compose restart

# Stop services
docker compose down

The services are configured with restart: unless-stopped, so they'll automatically restart after reboots or crashes.

Step 3: Configure n8n Webhook

1. Open http://localhost:5678 in your browser
2. Log in with the default credentials:
   • Username: admin
   • Password: admin
3. Create a new workflow
4. Add a Webhook node to your workflow
5. Configure the webhook:
   • HTTP Method: POST
   • Path: whinself-incoming
6. Activate the workflow to make the production URL live

💡 Example Workflow Available: If you prefer to get started quickly, you can download a complete example workflow that's already configured. Go to Step 5 to import the whinself-n8n-workflow.json file that includes all necessary nodes pre-configured.

Note: Whinself posts to http://n8n:5678/webhook/whinself-incoming inside the Docker network. If you test from your host machine, use http://localhost:5678/webhook/whinself-incoming.

Step 4: Connect WhatsApp to Whinself

1. Open http://localhost:8888 in your browser
2. Sign in or create your account if needed
3. In the dashboard, locate the QR code section
4. Open WhatsApp on your mobile device
5. Go to Settings > Linked Devices > Link a Device
6. Scan the QR code displayed on the Whinself dashboard
7. Once connected, incoming messages will be forwarded to your n8n webhook

Step 5: Create the Reply Workflow

Now you'll create an n8n workflow that can automatically reply to incoming WhatsApp messages.

💡 Example Workflow Available: You can download a complete working example: whinself-n8n-workflow.json that you can import directly into n8n. This workflow includes all necessary nodes pre-configured.

Quick Start: Import Example Workflow

For a quick start, you can import the provided example workflow:

1. Download the example workflow: Click here to download the whinself-n8n-workflow.json file
2. In n8n, go to Workflows and click Import from File
3. Select the downloaded whinself-n8n-workflow.json file
4. The workflow will be imported with all nodes pre-configured
5. Activate the workflow to start receiving messages

The example workflow includes:

• Webhook node configured for whinself-incoming path
• Code node that extracts the chat JID and prepares the reply
• HTTP Request node that sends the reply back to Whinself
• Respond to Webhook node for proper webhook response

Option A: Function Node + HTTP Request

This approach uses two nodes for better separation of concerns:

1. Function Node Configuration

Add a Function node after the Webhook node with this code:

const body = (items[0].json?.body ?? items[0].json) || {};
const jid = body?.event?.Info?.Chat;

if (!jid) {
  return [{ json: { ok: false, error: "Missing event.Info.Chat" } }];
}

return [
  {
    json: {
      ok: true,
      jid,
      text: "Hello! This is an automated reply from n8n.",
    },
  },
];

2. HTTP Request Node Configuration

Add an HTTP Request node after the Function node:

• Method: POST
• URL: http://whinself:8888/wspout
• Send: Body
• Content Type: JSON
• Body JSON:

{
  "jid": "={{$json.jid}}",
  "text": "={{$json.text}}"
}

Option B: Single Function Node

For a more compact approach, use a single Function node that handles both processing and sending:

const body = (items[0].json?.body ?? items[0].json) || {};
const jid = body?.event?.Info?.Chat;

if (!jid) {
  return [{ json: { ok: false, error: "Missing event.Info.Chat" } }];
}

const res = await this.helpers.httpRequest({
  method: "POST",
  url: "http://whinself:8888/wspout",
  json: true,
  body: { jid, text: "Hello! This is an automated reply from n8n." },
  timeout: 10000,
});

return [{ json: { ok: true, sentTo: jid, whinselfResponse: res } }];

Step 6: Test Your Setup

Test the Webhook

You can test your webhook setup using curl:

curl -X POST http://localhost:5678/webhook/whinself-incoming \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "Info": {
        "Chat": "[email protected]",
        "Sender": "[email protected]",
        "Type": "text",
        "PushName": "Tester",
        "Timestamp": "2025-01-15T12:34:56+02:00"
      },
      "Message": {
        "conversation": "Test message from curl"
      }
    },
    "phone": "34600000000",
    "slotid": "my-bot"
  }'

Test with Real WhatsApp Messages

1. Send a message to your connected WhatsApp number
2. Check the n8n workflow execution logs
3. Verify that the automated reply is sent back

Troubleshooting

Common Issues

QR Code Not Showing

• Ensure you're signed in to Whinself at http://localhost:8888
• Check Whinself logs: docker compose logs -f whinself
• Visit http://localhost:8888/events/logs for live logs (if LOGSSE=true)

Webhook Not Receiving Data

• Verify the webhook path matches: whinself-incoming
• Check that the workflow is activated in n8n
• Ensure the NRURL environment variable is correctly set

Port Configuration Issues

• Make sure PORTIN=8888 matches the port mapping 8888:8888
• If you change ports, update both the environment variable and port mapping

Payload Structure Your webhook payload typically looks like this:

{
  "headers": {...},
  "params": {...},
  "query": {...},
  "body": {
    "event": {
      "Info": {...},
      "Message": {...}
    }
  }
}

Access fields using {{$json.body.event...}} in n8n expressions.

Network Addressing

• Inside Docker network: Use http://n8n:5678/... and http://whinself:8888/...
• From host machine: Use http://localhost:5678/... and http://localhost:8888/...

Security Considerations

Before deploying to production:

1. Change default credentials:

   • Update N8N_BASIC_AUTH_USER and N8N_BASIC_AUTH_PASSWORD
   • Use strong, unique passwords

2. Set a strong encryption key:

   • Replace N8N_ENCRYPTION_KEY with a long, random value
   • Generate using: openssl rand -base64 32

3. Network security:

   • Consider placing services behind a reverse proxy
   • Restrict exposed ports if not needed externally
   • Use HTTPS in production environments

Advanced Workflow Ideas

Once you have the basic setup working, you can extend your workflows with:

• Conditional responses based on message content
• Database integration to store conversation history
• External API calls to fetch dynamic data
• Multi-step conversations with state management
• File handling for images, documents, and media
• Scheduled messages and reminders
• Integration with CRM systems for customer support

Clean Shutdown and Restart

# Stop all services
docker compose down

# Start services in background
docker compose up -d

# Quick restart without removing containers
docker compose restart

Next Steps

Now that you have Whinself and n8n working together, you can:

• Explore more complex n8n workflows
• Integrate with other services and APIs
• Build sophisticated WhatsApp chatbots
• Set up monitoring and logging
• Deploy to production environments

For more advanced topics, check out our Advanced Topics section.

---

Important Disclaimer: Whinself is an unofficial third-party tool that connects to the WhatsApp network using your personal WhatsApp account. It is not affiliated with, authorized, maintained, sponsored, or endorsed by WhatsApp or Meta Platforms, Inc. By using this software, you are responsible for ensuring your usage complies with WhatsApp's Terms of Service.