WhatsApp Real-Time Message API Receive WhatsApp messages in real-time and forward them instantly to your webhook or Telegram. All messages are also stored in an Apify Dataset for later access. ## Quick Start - QR Code Authentication First time only - your session is saved automatically for future runs. 1. Start the Actor (it runs in Standby mode automatically) 2. Access the API at: https://clearpath--whatsapp-real-time-message-api.apify.actor 3. Call /qr to get the QR code, or watch the logs 4. Open WhatsApp on your phone > Settings > Linked Devices > Link a Device 5. Scan the QR code 6. Messages start flowing to your webhook/Telegram immediately > Your session persists in a Key-Value Store. Future runs reconnect automatically without QR scanning. ## Pricing $29/month - Unlimited messages, all features included. - 1-day free trial - Webhook forwarding with HMAC signing - Telegram integration - Media download (images, videos, documents, audio, stickers) - Message filtering and API endpoints - Session persistence across runs You also pay standard Apify platform costs for compute and storage. ## Actor Input Screenshot ## How It Works The Actor runs continuously in Standby mode, capturing every WhatsApp message in real-time. Your WhatsApp ──> Actor (always running) ──> Webhook / Telegram │ └──> Apify Dataset (access via /messages) All messages are automatically: 1. Stored in Apify Dataset (access anytime via /messages endpoint) 2. Pushed to your webhook and/or Telegram (if configured) ### Keep It Running (Important!) Apify pauses idle Actors after ~5 minutes of no HTTP requests. Messages are lost while paused. To capture messages 24/7, ping /health every 4 minutes: - Use UptimeRobot (free), cron job, or any monitoring tool - Your WhatsApp session is saved - no QR rescan needed after restart - Actor wakes instantly when any endpoint is called ## Session Persistence Your WhatsApp session is automatically saved to a Key-Value Store, so you only need to scan the QR code once. How it works: - On first run, scan the QR code to link your WhatsApp - Session credentials are stored in a named KV store (whatsapp-auth-realtime by default) - Subsequent runs automatically reconnect using the saved session - No QR code needed unless the session becomes invalid When you need to re-scan: - You manually unlink the device from WhatsApp settings - The session expires (rare, typically months of inactivity) - You delete the auth KV store - You change the authStoreName input to a different value Multiple WhatsApp accounts: Use different authStoreName values to maintain separate sessions: json { "authStoreName": "whatsapp-auth-account-2" } ## Input Options ### Notification Settings | Field | Type | Default | Description | |-------|------|---------|-------------| | enableWebhook | boolean | false | Forward incoming messages to a webhook URL | | webhookUrl | string | - | Your webhook endpoint (required if webhook enabled) | | webhookSecret | string | - | Secret for HMAC-SHA256 signature verification | | enableTelegram | boolean | false | Forward messages to Telegram | | telegramChatId | string | - | Your Telegram chat/user ID (required if Telegram enabled) | > Validation: On startup, the Actor verifies webhook connectivity (POST test) and Telegram access (bot token + chat reachability). Invalid or unreachable channels are disabled with a warning—the Actor continues running. ### Message Filtering | Field | Type | Default | Description | |-------|------|---------|-------------| | chatFilter | string | all | Filter by chat type: all, groups, or private | | includeStatuses | boolean | false | Include WhatsApp Status (story) updates | | includeFromMe | boolean | true | Include messages you send from the linked device | | downloadMedia | array | all types | Media types to download: images, videos, documents, audio, stickers | ### Storage Settings | Field | Type | Default | Description | |-------|------|---------|-------------| | messageDatasetName | string | default | Dataset name for storing messages | | authStoreName | string | whatsapp-auth-realtime | KV store name for session persistence | ## Input Examples ### Webhook Integration Forward all messages to your server with signature verification: json { "enableWebhook": true, "webhookUrl": "https://your-server.com/whatsapp-webhook", "webhookSecret": "your-secret-key-here" } ### Telegram Notifications Get messages delivered to your Telegram (requires TELEGRAM_BOT_TOKEN environment variable): json { "enableTelegram": true, "telegramChatId": "123456789" } ### Groups Only, Text Only Monitor group chats without downloading media: json { "enableWebhook": true, "webhookUrl": "https://your-server.com/hook", "chatFilter": "groups", "downloadMedia": [], "includeFromMe": false } ### Full Setup with Both Channels json { "enableWebhook": true, "webhookUrl": "https://your-server.com/whatsapp", "webhookSecret": "hmac-secret", "enableTelegram": true, "telegramChatId": "123456789", "chatFilter": "all", "includeStatuses": false, "downloadMedia": ["images", "documents"] } ## HTTP API Endpoints Base URL: https://clearpath--whatsapp-real-time-message-api.apify.actor Authentication: Pass your Apify API token as a query parameter: ?token=YOUR_API_TOKEN The Actor exposes these endpoints while running in Standby mode: ### GET /health Returns connection status and metrics. json { "status": "ok", "uptimeSec": 3600, "whatsapp": { "connected": true, "connectionState": "open", "qrRequired": false }, "metrics": { "messagesReceived": 142, "messagesStored": 140, "messagesFiltered": 2, "webhookSent": 135, "webhookFailed": 5, "telegramSent": 130, "telegramFailed": 0 } } ### GET /qr Get the QR code for WhatsApp linking (if not yet connected). json { "status": "qr_available", "qr": "2@ABC123...", "generatedAt": "2024-12-04T10:30:00.000Z", "ageSec": 15 } If already connected: json { "status": "connected", "message": "Already connected to WhatsApp" } ### GET /messages Fetch stored messages with pagination. Query parameters: - limit (default: 100) - Number of messages to return - offset (default: 0) - Starting position - desc (default: false) - Set to true for newest messages first json { "items": [...], "total": 1042, "offset": 0, "limit": 100, "desc": false } ### GET /status Simple connection check. json { "connected": true, "connectionState": "open" } ## Webhook Payload Format Each message is POSTed to your webhook with this structure: ### Text Message json { "event": "whatsapp_message", "receivedAt": "2024-12-04T10:30:45.123Z", "data": { "messageId": "3EB0A1B2C3D4E5F6G7H8", "from": "14155551234@s.whatsapp.net", "fromMe": false, "timestamp": "2024-12-04T10:30:45.000Z", "messageType": "conversation", "text": "Hey, are you free for lunch today?", "chatId": "14155551234@s.whatsapp.net", "chatType": "private", "chatName": "Sarah Miller", "fromName": "Sarah Miller" } } ### Image Message json { "event": "whatsapp_message", "receivedAt": "2024-12-04T10:35:00.000Z", "data": { "messageId": "3EB0B2C3D4E5F6G7H8I9", "from": "14155551234@s.whatsapp.net", "fromMe": false, "timestamp": "2024-12-04T10:35:00.000Z", "messageType": "image", "text": "Check out this view!", "chatId": "14155551234@s.whatsapp.net", "chatType": "private", "chatName": "Sarah Miller", "fromName": "Sarah Miller", "media": { "messageType": "image", "mimetype": "image/jpeg", "fileSize": 245678, "width": 1920, "height": 1080, "caption": "Check out this view!", "url": "https://api.apify.com/v2/key-value-stores/abc123/records/media-3EB0B2C3.jpg", "downloadStatus": "downloaded" } } } ### Group Message json { "event": "whatsapp_message", "receivedAt": "2024-12-04T11:00:00.000Z", "data": { "messageId": "3EB0C3D4E5F6G7H8I9J0", "from": "14155559876@s.whatsapp.net", "fromMe": false, "timestamp": "2024-12-04T11:00:00.000Z", "messageType": "conversation", "text": "Meeting moved to 3 PM", "chatId": "120363000000000001@g.us", "chatType": "group", "chatName": "Weekend Tennis Group", "fromName": "John Doe" } } ### Location Message json { "event": "whatsapp_message", "data": { "messageId": "3EB0D4E5F6G7H8I9J0K1", "messageType": "location", "chatId": "14155551234@s.whatsapp.net", "chatType": "private", "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "Ferry Building", "address": "San Francisco, CA", "isLive": false } } } ### Reaction json { "event": "whatsapp_message", "data": { "messageId": "3EB0E5F6G7H8I9J0K1L2", "messageType": "reaction", "chatId": "14155551234@s.whatsapp.net", "reaction": { "text": "❤️", "targetMessageId": "3EB0A1B2C3D4E5F6G7H8" } } } ## Webhook HMAC Verification If you configure webhookSecret, each request includes an X-Signature header with an HMAC-SHA256 signature of the request body. Node.js verification example: javascript const crypto = require('crypto'); function verifyWebhook(req, secret) { const signature = req.headers['x-signature']; const body = req.rawBody; // Raw JSON string, not parsed const expectedSignature = crypto .createHmac('sha256', secret) .update(body) .digest('hex'); return signature === expectedSignature; } // Express middleware example app.post('/whatsapp-webhook', express.raw({ type: 'application/json' }), (req, res) => { if (!verifyWebhook(req, 'your-secret-key')) { return res.status(401).json({ error: 'Invalid signature' }); } const message = JSON.parse(req.body); console.log('Received:', message.data.text); res.sendStatus(200); }); ## Telegram Integration To receive messages on Telegram: 1. Get your chat ID (message @userinfobot) 2. Set enableTelegram: true and telegramChatId in your input ### Important: Bot Permission Setup Before notifications will work, you must message the bot first: 1. Find the bot - Search for @whatsapp_realtime_api_bot on Telegram 2. Send any message - Type /start or any text to initiate contact 3. Done! - The bot can now send you notifications Message format in Telegram: 📱 Private: Sarah Miller 👤 From: Sarah Miller 🕐 2024-12-04, 10:30 AM Hey, are you free for lunch today? For media messages, the Telegram bot sends the file directly with a caption containing the message details. ## Message Output Format Messages stored in the Dataset have this structure: json { "id": "3EB0A1B2C3D4E5F6G7H8", "from": "14155551234@s.whatsapp.net", "fromMe": false, "timestamp": "2024-12-04T10:30:45.000Z", "messageType": "conversation", "text": "Hello!", "chatId": "14155551234@s.whatsapp.net", "chatType": "private", "chatName": "Sarah Miller", "fromName": "Sarah Miller", "quotedMessageId": null, "media": null, "location": null, "contact": null, "reaction": null, "poll": null } ### Message Types | Type | Description | |------|-------------| | conversation | Plain text message | | extendedText | Text with link preview or quoted reply | | image | Image message | | video | Video message | | audio | Audio/voice message | | document | File attachment | | sticker | Sticker | | location | Static location | | liveLocation | Live location sharing | | contact | Shared contact | | contacts | Multiple shared contacts | | reaction | Emoji reaction | | poll | Poll | | pollUpdate | Poll vote | ### Media Object When media is downloaded, the media field contains: json { "type": "image", "mimetype": "image/jpeg", "fileSize": 245678, "width": 1920, "height": 1080, "seconds": null, "caption": "Check this out!", "fileName": null, "url": "https://api.apify.com/v2/key-value-stores/xxx/records/media-abc123.jpg", "downloadStatus": "downloaded", "downloadedAt": "2024-12-04T10:30:50.000Z" } Download status values: - downloaded - Successfully downloaded and stored - failed - Download failed after retries - expired - Media no longer available on WhatsApp servers (common for older messages) ### Chat ID Formats - Private chats: {phone}@s.whatsapp.net (e.g., 14155551234@s.whatsapp.net) - Group chats: {id}@g.us (e.g., 120363000000000001@g.us) - Status updates: status@broadcast ## Data Privacy All data is stored exclusively in your private Apify storage: - Messages: Stored in your private Dataset - Media: Stored in your private Key-Value Store - Session: Stored in a named KV store (whatsapp-auth-realtime) The Actor developer has no access to your data. All storage is private to your Apify account. ## Troubleshooting QR code not appearing - Wait for the Actor to fully start (check /health endpoint) - Try the /qr endpoint directly to get the QR code data - Ensure no other device is already linked with the same session Webhook not receiving messages - Verify your webhook URL is publicly accessible - Check the Actor logs for webhook errors - Confirm the webhook returns HTTP 200 within 10 seconds - Review /health metrics for webhookFailed count "Already connected" but not receiving messages - The WhatsApp session may be stale. Delete the auth store and re-link - Check if messages are filtered by your chatFilter settings - Verify includeFromMe setting if testing with your own messages Actor keeps stopping - Normal idle timeout behavior - see Keep It Running section - Set up UptimeRobot or cron to ping /health every 4 minutes Media download failing - Media on WhatsApp servers expires after ~30 days - Large files may timeout - check downloadMedia settings - Verify you're downloading the correct media types Session not reconnecting (unexpected QR code) - Check if the auth KV store exists (whatsapp-auth-realtime) - Verify you're using the same authStoreName as previous runs - The device may have been unlinked from WhatsApp settings on your phone ## Support Questions or issues? Contact: max@mapa.slmail.me