Skip to main content
Connect OpenClaw to your self-hosted Meepa instance so your AI assistant can read and send messages across your servers.

​
Overview

Meepa exposes a Bot API that OpenClaw connects to as a channel plugin. The integration uses:
  • Bot Gateway WebSocket (/api/bot-gateway) for receiving real-time events
  • REST API for sending messages, reactions, and other actions
  • Bot token authentication (Authorization: Bot <token>)

​
Quick start

Install the official OpenClaw channel plugin: 
openclaw plugins install openclaw-channel-meepachat

​
Prerequisites

  • A running Meepa instance accessible from your OpenClaw host
  • Admin or owner role on the Meepa server you want to connect
  • OpenClaw installed and running (docs)

​
Step 1: Create a bot

Create a bot in Meepa to act as the OpenClaw connection. You can do this through the web UI (Server Settings > Bots > Create Bot) or via the CLI: 
meepachat bots create --username openclaw --server SERVER_ID --display-name "OpenClaw"
Save the bot token from the response — you’ll need it for OpenClaw configuration.
Treat bot tokens like passwords. Never commit them to source control or expose them in client-side code. Regenerate compromised tokens with meepachat bots regenerate-token BOT_ID.

​
Step 2: Add the bot to servers

The bot is automatically added to the server specified during creation. To add it to additional servers: 
meepachat bots add-to-server BOT_ID --server SERVER_ID
The bot auto-joins all channels in each server it’s added to.

​
Step 3: Configure OpenClaw

Add the Meepa channel to your OpenClaw configuration file (config.json or config.json5): 
{
  channels: {
    meepachat: {
      enabled: true,

      // Your Meepa instance URL (required)
      url: "https://your-meepa-instance.example.com",

      // Bot token from Step 1 (recommended: use env var)
      token: "$MEEPACHAT_BOT_TOKEN",

      // TLS verification (default: true)
      // Set to false for self-signed certificates
      tlsVerify: true,

      // Server and channel configuration
      servers: {
        SERVER_ID: {
          requireMention: false,
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
            },
          },
        },
      },

      // WebSocket reconnection settings
      retry: {
        attempts: 5,
        minDelayMs: 1000,
        maxDelayMs: 30000,
      },
    },
  },
}

​
Environment variables

Set the bot token as an environment variable instead of putting it in the config: 
export MEEPACHAT_BOT_TOKEN="bot-uuid.secret-token"
export MEEPACHAT_URL="https://your-meepa-instance.example.com"

​
Step 4: Start the gateway

openclaw gateway start
OpenClaw will:
  1. Connect to wss://your-meepa-instance.example.com/api/bot-gateway?token=<bot-token>
  2. Receive a ready event with the bot’s user info, servers, and channels
  3. Auto-subscribe to all channels the bot has access to
  4. Begin receiving real-time events
You should see in the logs: 
[meepachat] Connected to your-meepa-instance.example.com
[meepachat] Bot "openclaw" ready - 1 server, 5 channels

​
How it works

​
Inbound (Meepa -> OpenClaw)

The bot connects to Meepa’s Bot Gateway WebSocket and receives events:
EventDescription
readyConnection established, includes user info and server list
message.createdNew message in a subscribed channel
message.updatedMessage was edited
message.deletedMessage was deleted
reaction.syncReactions changed on a message

​
Outbound (OpenClaw -> Meepa)

The plugin sends responses via Meepa’s REST API:
ActionMethodEndpoint
Send messagePOST/api/servers/{serverId}/channels/{channelId}/messages
Reply in threadPOSTSame endpoint with threadId in body
Add reactionPUT/api/messages/{messageId}/reactions/{emoji}
Remove reactionDELETE/api/messages/{messageId}/reactions/{emoji}
Upload filePOST/api/upload
All requests use: 
Authorization: Bot <token>

​
Self-hosted considerations

​
Network access

OpenClaw must be able to reach your Meepa instance over the network:
SetupURL ExampleNotes
Same machinehttp://localhost:8091No TLS needed
Local networkhttp://192.168.1.50:8091Use IP or local DNS
Tailscalehttps://chat.your-tailnetBoth hosts on Tailscale
Public domainhttps://chat.example.comNeeds valid TLS cert
Docker networkhttp://meepachat:8091Same compose stack

​
Self-signed certificates

If your Meepa instance uses a self-signed or private CA certificate: 
{
  channels: {
    meepachat: {
      url: "https://chat.internal",
      token: "$MEEPACHAT_BOT_TOKEN",
      tlsVerify: false,
    },
  },
}

​
Running in Docker

If both OpenClaw and Meepa run in Docker, add OpenClaw to Meepa’s network: 
# docker-compose.yml (OpenClaw)
services:
  openclaw:
    image: openclaw/openclaw
    environment:
      MEEPACHAT_URL: http://meepachat:8091
      MEEPACHAT_BOT_TOKEN: "bot-uuid.secret-token"
    networks:
      - meepachat_default

networks:
  meepachat_default:
    external: true

​
WebSocket keepalive

The Bot Gateway sends WebSocket pings every 30 seconds. The plugin must respond with pong frames (handled automatically by most WebSocket libraries). If no pong is received within 60 seconds, the connection is closed. The plugin can also send application-level pings: 
{ "type": "ping" }
Response: 
{ "type": "pong" }

​
Troubleshooting

  • Verify the bot has been added to the server: meepachat bots servers BOT_ID
  • Check that the bot is a member of the expected channels (it auto-joins on server add)
  • Ensure requireMention is set correctly — if true, the bot only responds when mentioned
  • Verify the Meepa URL is reachable: curl https://your-meepa-instance.example.com/api/health - Check firewall rules and Tailscale ACLs if applicable - If using Docker, ensure containers are on the same network
  • For self-signed certs, set tlsVerify: false in the OpenClaw config - Ensure the URL scheme matches your TLS setup (https:// vs http://)
  • Tokens have the format BOT_ID.SECRET — ensure you copied the full value
  • Regenerate if needed: meepachat bots regenerate-token BOT_ID