WhatsApp SMS Actor with MCP Support

A powerful Apify Actor that enables WhatsApp messaging through the Message Control Protocol (MCP). This Actor can operate in two modes: sending individual messages or running as an MCP server for AI agent integration.

Features

• Two Operation Modes:

  • Send Mode: Send individual WhatsApp messages
  • Server Mode: Run as an MCP server for AI agent integration

• QR Code Authentication: Secure WhatsApp Web authentication via QR code

• Session Persistence: Maintains authenticated sessions across runs

• REST API: Full HTTP API for message sending and status checking

• Dataset Storage: All messages are stored in Apify datasets for tracking

Configuration

Input Parameters

Parameter	Type	Description	Required	Default
mode	string	Operation mode: send or server	Yes	send
phoneNumber	string	WhatsApp phone number (with country code)	For send mode	+1234567890
message	string	Message text to send	For send mode	-
serverPort	integer	Port for MCP server	For server mode	3000
useQRAuth	boolean	Enable QR code authentication	No	true

Example Input (Send Mode)

{
  "mode": "send",
  "phoneNumber": "+1234567890",
  "message": "Hello from Apify WhatsApp Actor!",
  "useQRAuth": true
}

Example Input (Server Mode)

{
  "mode": "server",
  "serverPort": 3000,
  "useQRAuth": true
}

Usage

Send Mode

1. Configure the input with mode: "send"
2. Provide phoneNumber and message
3. Run the Actor
4. Scan the QR code when prompted (first time only)
5. Message will be sent automatically

Server Mode

1. Configure the input with mode: "server"
2. Run the Actor
3. Scan the QR code when prompted (first time only)
4. Use the REST API endpoints:

API Endpoints

Health Check

$GET http://localhost:3000/health

Get QR Code

$GET http://localhost:3000/api/qr

Send Message

POST http://localhost:3000/api/messages/send
Content-Type: application/json

{
  "to": "+1234567890",
  "message": "Hello from WhatsApp MCP!"
}

cURL Example

curl -X POST http://localhost:3000/api/messages/send \
  -H "Content-Type: application/json" \
  -d '{"to": "+1234567890", "message": "Hello from WhatsApp MCP Server!"}'

Authentication

QR Code Authentication

The Actor uses WhatsApp Web's QR code authentication:

1. First Run: A QR code will be displayed in the console
2. Scan: Open WhatsApp on your phone → Settings → Linked Devices → Link a Device
3. Scan the QR code displayed in the terminal
4. Session Saved: The session is stored in the Apify key-value store
5. Subsequent Runs: No QR code needed (session persists for ~20 days)

Integration with AI Agents

MCP Client Configuration

Add this to your AI client's configuration file (e.g., Claude Desktop config.json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "apify",
      "args": ["run", "--purge"]
    }
  }
}

Using with AI Prompts

Once configured, AI agents can send WhatsApp messages:

// AI agent can invoke:
const response = await client.invoke("send-whatsapp-message", {
  to: "+1234567890",
  message: "Hello, how are you today?"
});

Output

All sent messages are saved to the Apify dataset with the following structure:

{
  "phoneNumber": "+1234567890",
  "message": "Hello from WhatsApp!",
  "status": "sent",
  "timestamp": "2025-11-05T04:00:00.000Z",
  "messageId": "3EB0XXXXX"
}

Local Development

Prerequisites

• Node.js >= 20.0.0
• Apify CLI installed
• WhatsApp mobile app

Installation

# Clone the repository
cd whatsapp_sms

# Install dependencies
npm install

# Run locally
apify run

Running the Actor Locally

Send Mode:

apify run
# Then scan QR code and wait for message to send

Server Mode: Set input mode to "server" in .actor/INPUT.json, then:

apify run
# Server will start on http://localhost:3000

Deployment

Deploy to Apify Platform

# Login to Apify
apify login

# Push Actor to platform
apify push

Technical Details

Dependencies

• @whiskeysockets/baileys: WhatsApp Web API implementation
• @modelcontextprotocol/sdk: MCP protocol support
• express: HTTP server for REST API
• qrcode-terminal: QR code display in terminal
• pino: Logging
• apify: Apify SDK
• crawlee: Web automation framework

Session Storage

Authentication sessions are stored in:

• Local: ./storage/key_value_stores/default/whatsapp_auth
• Cloud: Apify key-value store (persistent across runs)

Architecture

┌─────────────────┐
│   Apify Actor   │
└────────┬────────┘
         │
    ┌────┴────┐
    │  Mode?  │
    └────┬────┘
         │
    ┌────┴─────────┐
    │              │
┌───▼───┐    ┌────▼────┐
│ Send  │    │ Server  │
│ Mode  │    │  Mode   │
└───┬───┘    └────┬────┘
    │             │
    │        ┌────▼────┐
    │        │ Express │
    │        │   API   │
    │        └────┬────┘
    │             │
    └─────┬───────┘
          │
    ┌─────▼──────┐
    │  Baileys   │
    │ WhatsApp   │
    └─────┬──────┘
          │
    ┌─────▼──────┐
    │  WhatsApp  │
    │    Web     │
    └────────────┘

Troubleshooting

QR Code Not Showing

• Ensure useQRAuth is set to true
• Check console output for errors

Session Expired

• Sessions expire after ~20 days
• Simply re-scan the QR code when prompted

Message Not Sending

• Verify phone number format includes country code (e.g., +1234567890)
• Ensure WhatsApp connection is established (check logs)
• Verify the recipient has WhatsApp installed

Connection Issues

• Check your internet connection
• Ensure WhatsApp is not logged out on your phone
• Try clearing the session and re-authenticating

Security Considerations

• Never share your authentication session files
• Use environment variables for sensitive configuration
• Respect WhatsApp's Terms of Service
• Implement rate limiting for bulk messaging
• Do not use for spam or unauthorized messaging

License

ISC

Support

For issues and questions:

• GitHub Issues: [Report here]
• Apify Community: https://community.apify.com/
• Documentation: See AGENTS.md for AI agent integration details