OpenClawBot - Unified Messaging API

Send messages to WhatsApp, Telegram, and Discord through a single API endpoint using OpenClaw.

OpenClawBot is an Apify Actor that runs as a real-time HTTP API (Standby mode), providing a unified interface for multi-channel messaging. Perfect for chatbots, notifications, alerts, and automation workflows.

✨ What can OpenClawBot do?

• ✅ WhatsApp Integration - Send messages via WhatsApp after one-time pairing
• ✅ Telegram Support - Send messages to users, groups, or channels via Telegram Bot
• ✅ Discord Integration - Send messages to Discord channels or users
• ✅ Unified API - Single /send endpoint for all channels
• ✅ Real-time HTTP API - Standby mode for instant responses
• ✅ Persistent Sessions - WhatsApp pairing survives restarts
• ✅ Secure - API key authentication, localhost-only gateway
• ✅ Reliable - Per-channel locks prevent race conditions

🚀 Quick Start

1. Deploy to Apify

Deploy this Actor to your Apify account and enable Standby mode.

2. Configure Secrets

Add these secrets in Apify Console:

Secret Name	Description
OPENCLAWBOT_API_KEY	Your API key for authenticating requests
TELEGRAM_BOT_TOKEN	Bot token from @BotFather (for Telegram)
DISCORD_BOT_TOKEN	Bot token from Discord Developer Portal

3. Start the Actor

Run the Actor with Standby mode enabled. It will:

1. Restore any saved OpenClaw profile
2. Start the OpenClaw gateway
3. Listen for HTTP requests on ACTOR_WEB_SERVER_PORT

4. Call the API

Authentication Required: You need TWO tokens to access the API:

1. Apify API Token: To reach the running actor (Platform level)
   • Pass as query param: ?token=YOUR_APIFY_TOKEN (found in Apify Console)
2. OpenClawBot API Key: To authorize the action (App level)
   • Pass in header: Authorization: Bearer YOUR_OPENCLAWBOT_KEY

Example:

# Health check (Platform auth only)
curl "https://openclawbot-happitap.apify.actor/health?token=YOUR_APIFY_TOKEN"

# Send a Telegram message (Both auths required)
curl -X POST "https://openclawbot-happitap.apify.actor/send?token=YOUR_APIFY_TOKEN" \
  -H "Authorization: Bearer YOUR_OPENCLAWBOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "target": "@username",
    "message": "Hello from OpenClawBot!"
  }'

Note: Verify your exact Standby URL in the Apify Console (Settings -> Standby URL).

⏱️ Standby Mode & Cold Starts

Important: This actor uses Apify's Standby mode for real-time HTTP responses.

How it works:

State	Response Time	What Happens
Actor Running	~100-500ms	Instant response
Cold Start	15-30 seconds	Container boots, OpenClaw initializes
After Idle (~3 min)	Actor shuts down	Next request triggers cold start

⚠️ First Request Delay

The first request after the actor has been idle will experience a cold start delay (15-30s). This is because:

1. Docker container needs to start
2. OpenClaw gateway needs to initialize
3. WhatsApp session needs to be restored (if any)

💡 Keep-Alive Recommendations

To avoid cold start delays, set up a keep-alive ping every 2 minutes:

# Using cron (every 2 minutes)
*/2 * * * * curl -s https://openclawbot-happitap.apify.actor/health > /dev/null

# Using Apify Scheduler
# Create a scheduled task to call /health every 2 minutes

Alternative: Use Apify Scheduler to ping /health every 2 minutes.

Note: Keep-alive pings will consume minimal compute credits but ensure instant message delivery.

📡 API Endpoints

GET /health

Check if the API server and OpenClaw gateway are running.

Response:

{
  "ok": true,
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "reachable": true
  },
  "uptimeSec": 12345
}

GET /status

Debug endpoint that runs openclaw status --all.

Response:

{
  "ok": true,
  "statusText": "..."
}

POST /send

Send a text message to any supported channel.

Headers:

• Authorization: Bearer <OPENCLAWBOT_API_KEY> (required if requireApiKey is true)

Request Body:

{
  "channel": "whatsapp | telegram | discord",
  "target": "+919876543210 | @username | channelId",
  "message": "Your message text",
  "account": "default",
  "options": {
    "replyTo": null,
    "threadId": null
  }
}

Target Format:

Channel	Target Format	Example
WhatsApp	E.164 phone number	+919876543210
Telegram	@username or chat ID	@johndoe or -1001234567890
Discord	Channel/User ID (17-20 digits)	123456789012345678

Success Response:

{
  "ok": true,
  "channel": "telegram",
  "target": "@john",
  "sentAt": "2026-02-03T08:10:00.000Z",
  "exitCode": 0,
  "stdout": "...",
  "stderr": ""
}

Error Response:

{
  "ok": false,
  "error": {
    "code": "NOT_PAIRED | INVALID_TARGET | GATEWAY_DOWN | OPENCLAW_ERROR",
    "message": "Human readable error"
  }
}

POST /whatsapp/pair

Start WhatsApp pairing to link your phone.

Headers:

• Authorization: Bearer <OPENCLAWBOT_API_KEY>

Request Body:

{
  "format": "auto | code | qrText | qrPngBase64",
  "account": "default"
}

Response:

{
  "ok": true,
  "account": "default",
  "pairing": {
    "code": "ABCD-EFGH",
    "qrText": "raw qr payload"
  },
  "qrPngBase64": "iVBORw0KGgo..."
}

⚙️ Input Configuration

Required Settings

Field	Type	Description
mode	string	"standby" for HTTP API mode
profileStoreKey	string	KV key for storing OpenClaw profile (e.g., "OPENCLAW_PROFILE_TAR_GZ")

Optional Settings

Field	Type	Default	Description
gatewayPort	number	18789	OpenClaw gateway port
gatewayHost	string	"127.0.0.1"	Gateway host binding
gatewayVerbose	boolean	false	Enable verbose logging (⚠️ may log secrets)
persistProfile	boolean	true	Save profile to KV store
profileSaveIntervalSec	number	60	Profile save interval in seconds
enableLocks	boolean	true	Enable per-channel mutex
requireApiKey	boolean	true	Require API key for POST endpoints
apiKeySecretName	string	"OPENCLAWBOT_API_KEY"	Secret name for API key
allowlistChannels	array	["whatsapp","telegram","discord"]	Allowed channels
maxMessageLength	number	4000	Maximum message length

💰 Pricing (Pay-Per-Event)

Event	Price	Rate
apify-actor-start	$0.00005	Per actor start
whatsapp-message-sent	$0.0015	$1.50 per 1,000 messages
telegram-message-sent	$0.0008	$0.80 per 1,000 messages
discord-message-sent	$0.0008	$0.80 per 1,000 messages
whatsapp-pairing	$0.01	$10 per 1,000 pairings
profile-save	$0.0001	$0.10 per 1,000 saves
status-check	$0.0001	$0.10 per 1,000 checks

🔒 Security

• API Key Authentication: All POST endpoints require Authorization: Bearer header
• Localhost Gateway: OpenClaw gateway binds to 127.0.0.1 only
• No Secret Logging: Bot tokens, phone numbers, and session data are never logged
• Profile Encryption: Stored in private Apify Key-Value Store

🛠️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Apify Container                         │
│                                                             │
│  ┌─────────────────┐    ┌──────────────────────────────┐   │
│  │   Express API   │◄──►│    OpenClaw Gateway          │   │
│  │  (Port from     │    │    (Port 18789, localhost)   │   │
│  │  ACTOR_WEB_     │    └──────────────────────────────┘   │
│  │  SERVER_PORT)   │                 │                     │
│  └────────┬────────┘                 ▼                     │
│           │              ┌──────────────────────────────┐  │
│           │              │     OpenClaw CLI             │  │
│           │              │  (message send, pair, etc)   │  │
│           │              └──────────────────────────────┘  │
│           │                          │                     │
│           ▼                          ▼                     │
│  ┌─────────────────────────────────────────────────────┐  │
│  │            Apify Key-Value Store                    │  │
│  │         (Profile persistence as tar.gz)             │  │
│  └─────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
       ┌──────────────────────────────────────────────┐
       │            Messaging Platforms               │
       │  WhatsApp  │   Telegram   │    Discord       │
       └──────────────────────────────────────────────┘

📋 Error Codes

Code	Description
UNAUTHORIZED	Missing or invalid API key
INVALID_CHANNEL	Channel not in allowlist
INVALID_TARGET	Target format doesn't match channel requirements
INVALID_MESSAGE	Message empty or too long
NOT_PAIRED	WhatsApp not paired (call /whatsapp/pair first)
GATEWAY_DOWN	OpenClaw gateway not reachable
OPENCLAW_ERROR	Error from OpenClaw CLI
INTERNAL_ERROR	Unexpected server error

🔧 Troubleshooting

WhatsApp pairing keeps expiring

• Make sure persistProfile is true
• Check that profileStoreKey is set correctly
• The profile is saved periodically (default: 60s) and on pairing

Gateway won't start

• Check Actor memory (minimum 1GB recommended)
• Verify OpenClaw is installed in the Docker image
• Check logs for gateway startup errors

Messages not sending

• Verify the target format matches the channel requirements
• For Telegram, ensure the bot has permission to message the user/channel
• For Discord, ensure the bot is in the server and has send permissions

📚 Reference Documentation

• Apify Standby Mode
• Apify Key-Value Store
• OpenClaw Documentation
• OpenClaw CLI
• OpenClaw npm package

🤝 Support

• 📧 Issues? Use the Issues tab
• 💬 Questions? Check troubleshooting section
• 🔧 Custom solution? Contact us

---

License: Apache-2.0 | Version: 1.0.0