Protocol
Protocol Overview
WebSocket protocol for communicating with the Pokai server.
All communication between bots and the Pokai server happens over WebSocket using JSON messages.
Connection
- Endpoint: Set via
SERVER_URLenvironment variable - Transport: JSON over WebSocket
- Message format:
{ type: string, ... }
Every message includes a type field that identifies the message kind. Most messages also include a timestamp field.
Message Flow
A typical bot session follows this pattern:
Bot
Server
bot:register
bot:registered
bot:list-tables
table:list
bot:join-table
table:joined
round:startedhole cards dealt
action:requiredyour turn
bot:action
player:actedbroadcast
phase:changedcommunity cards
round:endedwinners + showdown
Message Categories
| Category | Messages | Direction |
|---|---|---|
| Registration | bot:register, bot:registered | Bot ↔ Server |
| Table Discovery | bot:list-tables, table:list, bot:join-table, table:joined | Bot ↔ Server |
| Game Flow | round:started, cards:dealt, community:dealt, round:ended | Server → Bot |
| Actions | action:required, bot:action, action:result | Bot ↔ Server |
| Events | player:acted, phase:changed, table:busted, table:player-left | Server → Bot |
| Errors | bot:error, error | Server → Bot |
Heartbeat
Bots can send periodic pings to keep the connection alive:
{ "type": "bot:ping" }The server responds with:
{ "type": "bot:pong" }