Build a MaxChat Bot

Use the docs sidebar topics to move through setup, coding, and deployment.

What This Uses

maxbot_hoster/src/index.js for API routes and gateway behavior, and ping_bot.py as the practical bot example.

Quick Flow

1) Create app + copy bot token
2) Install bot to a server
3) Connect to /gateway and IDENTIFY
4) Use /api/bot/messages/send and other bot routes

Create App

Start in the Developer Portal, then install your bot app into a server.

1) Create the app

Create a new app in Developer Portal. Relevant owner routes from index.js:
GET /api/dev/apps
POST /api/dev/apps
POST /api/dev/apps/:appId/name
POST /api/dev/apps/:appId/reset-token

2) Install to a server

Install your app into a server using:
POST /api/dev/apps/:appId/install
Your bot must be installed before bot-token routes like /api/bot/messages/send will work.

3) Save your bot token

Use bot auth for bot routes:
Authorization: Bearer <BOT_TOKEN>
or
Authorization: Bot <BOT_TOKEN>

Code Bot

Pattern from ping_bot.py: websocket gateway + REST commands.

1) Install deps

pip install requests websockets

2) Connect gateway + identify

gw = API_BASE.replace("https://", "wss://").replace("http://", "ws://") + "/gateway"
hello = json.loads(await ws.recv())
await ws.send(json.dumps({"op": "IDENTIFY", "d": {"token": BOT_TOKEN}}))
await ws.send(json.dumps({"op": "HEARTBEAT", "d": int(time.time() * 1000)}))

3) Send messages with bot routes

requests.post(
  f"{API_BASE}/api/bot/messages/send",
  headers={"Authorization": f"Bearer {BOT_TOKEN}", "Content-Type": "application/json"},
  data=json.dumps({"serverId": "...", "channelId": "...", "content": "Pong!"}),
  timeout=15
)

Run Bot

Use environment variables and start your script.

1) Set env vars

MAXBOT_API_BASE=https://your-api-base
MAXBOT_TOKEN=mbt_...

2) Start script

python ping_bot.py

3) Verify

Health check:
GET /health
Bootstrap info:
GET /api?bot=1

Routes

Core endpoints exposed by maxbot_hoster/src/index.js.

Auth

User auth header: Authorization: Bearer <FIREBASE_ID_TOKEN>
Bot auth header: Authorization: Bearer <BOT_TOKEN> or Authorization: Bot <BOT_TOKEN>

Core Bot Routes

POST /api/bot/messages/send
POST /api/bot/messages/edit
POST /api/bot/messages/delete
POST /api/bot/presence
POST /api/bot/profile
POST /api/bot/roles/add
POST /api/bot/roles/remove
POST /api/bot/members/nick
POST /api/bot/channels/create
POST /api/bot/channels/edit
POST /api/bot/channels/delete
POST /api/bot/members/kick
POST /api/bot/members/ban
POST /api/bot/servers/rename
POST /api/bot/invites/create

Developer Helper

GET /api/dev/apps/:appId/invite – retrieve a shareable invite URL for your bot

Gateway

WebSocket endpoint: /gateway
Receive: {"op":"HELLO","d":{"heartbeat_interval":30000}}
Send: {"op":"IDENTIFY","d":{"token":"<BOT_TOKEN>"}}
Heartbeat: {"op":"HEARTBEAT","d":<timestamp>}