MeepaGateway

Connect MeepaGateway AI agents to your MeepaChat instance

Overview

MeepaGateway is a self-hosted bot gateway that connects AI agents (Claude, GPT-4, etc.) to chat platforms. The MeepaChat connector uses the Bot Gateway WebSocket to receive real-time events and the REST API to send responses.

Step 1: Create a bot in MeepaChat

You need a bot account for MeepaGateway to authenticate with. Create one using any of these methods:

Web UI

Go to Server Settings → Bots → Create Bot. Enter a username and display name, then click Create. Copy the bot token immediately — it’s only shown once.

CLI

meepachat bots create --username meepa --server <serverID>

API

curl -X POST https://your-meepa-instance.example.com/api/bots \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "meepa",
    "display_name": "Meepa",
    "server_id": "YOUR_SERVER_ID"
  }'

Save the bot token — it has the format BOT_ID.SECRET and is only shown once.

Treat bot tokens like passwords. Never commit them to source control.

Step 2: Install MeepaGateway

Homebrew (macOS/Linux)

brew install bogpad/tap/meepagateway

Step 3: Configure the MeepaChat connector

Add a MeepaChat connector to your agent’s config. In ~/.meepagateway/agents/<id>/agent.yaml:

connectors:
  - type: meepachat
    url: "wss://your-meepa-instance.example.com/api/bot-gateway"
    bot_token: "YOUR_BOT_ID.YOUR_BOT_SECRET"

Store the token in an environment variable instead of the config file:

export MEEPA_BOT_TOKEN="YOUR_BOT_ID.YOUR_BOT_SECRET"

Then reference it in the config:

connectors:
  - type: meepachat
    url: "wss://your-meepa-instance.example.com/api/bot-gateway"
    bot_token: "$MEEPA_BOT_TOKEN"

Step 4: Configure an AI provider

In ~/.meepagateway/config.yaml:

providers:
  primary: anthropic
  providers:
    anthropic:
      api_key_env: ANTHROPIC_API_KEY
      model: claude-sonnet-4-6

Set your API key:

export ANTHROPIC_API_KEY="sk-ant-..."

Step 5: Start the gateway

meepagateway start

MeepaGateway connects to your MeepaChat instance, receives a ready event with the bot’s servers and channels, and begins responding to messages.

Self-hosted considerations

Setup	URL format	Notes
Same machine	ws://localhost:8091/api/bot-gateway	No TLS needed
Local network	ws://192.168.1.50:8091/api/bot-gateway	Use IP or local DNS
Tailscale	wss://chat.your-tailnet/api/bot-gateway	Both hosts on Tailscale
Public domain	wss://chat.example.com/api/bot-gateway	Needs valid TLS cert
Docker network	ws://meepachat:8091/api/bot-gateway	Same compose stack

Self-signed certificates

For instances with a private CA:

export SSL_CERT_FILE=/path/to/ca.crt
meepagateway start

Or disable TLS verification (not recommended for production):

connectors:
  - type: meepachat
    url: "wss://chat.internal/api/bot-gateway"
    bot_token: "$MEEPA_BOT_TOKEN"
    tls_verify: false

How it works

1. MeepaGateway opens a WebSocket to /api/bot-gateway using the bot token
2. MeepaChat sends a ready event with all servers and channels the bot belongs to
3. The gateway auto-subscribes to all accessible channels
4. Incoming message.created events are routed to the configured AI agent
5. The agent’s response is sent back via POST /api/servers/{id}/channels/{id}/messages

For detailed Gateway configuration — agents, skills, cron jobs, and multi-agent routing — see the MeepaGateway documentation.