Authentication

Two kinds of key. rg_admin_… is the platform key and can reach every tenant. rg_live_… is tenant-scoped and can only ever touch its own tenant. Send it as Authorization: Bearer <key>.

curl http://localhost:8787/v1/tenants \
  -H "Authorization: Bearer $RELAY_ADMIN_KEY"

Endpoints

Create a tenant

curl -X POST http://localhost:8787/v1/tenants \
  -H "Authorization: Bearer $RELAY_ADMIN_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Sara'"'"'s Phone Shop"}'

The response contains the tenant's rg_live_… key. It is shown once and stored only as a hash.

Send a message

curl -X POST http://localhost:8787/v1/messages \
  -H "Authorization: Bearer $TENANT_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chat_id": 15551234567,
    "text": "Your order #412 ships tomorrow.",
    "parse_mode": "HTML"
  }'

chat_id is a numeric user id or a @username. Rate limits are enforced for you: about 1 message/second per chat, 20/minute per group, 30/second overall.

Webhooks

Register a URL and we POST every event to it. The body is signed: x-relay-signature: sha256=…, computed with the secret we returned at registration. Verify it with an HMAC-SHA256 over the raw body.

curl -X POST http://localhost:8787/v1/webhooks \
  -H "Authorization: Bearer $TENANT_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://example.com/hooks/telegram",
    "events": ["message.sent", "message.received"]
  }'

MCP tools

The same operations are exposed to AI agents over MCP. Start it with node dist/mcp.js and point your client at it.

Configuration