sometimespolls and game starts
bots can create and close their own polls and start games. voting is available only through an installing user’s explicit permission.
poll contract
Poll has id, message_id, title, options, multiple, public_votes, closes_at and revision. title is 1–200 weighted characters; 2–20 options each have a string ID and 1–100 weighted characters of text. duration_seconds is 60–2,592,000. a result read adds closed, voters (the total count), winner_ids and each option’s count. option voters are basic identities only when public_votes is true. anonymous results omit individual selections. voting returns only the installer’s own_option_ids and the new revision.
poll routes
creating a poll does not require plain-message send. closing requires matching author ownership. voting accepts option_ids as a full replacement, an empty list to clear, and at most one ID when multiple is false. repeated identical writes are idempotent. poll-result permission does not authorize voting, and bot actor is always rejected on the vote route.
scroll the table horizontally to see all columns.
| method and path | request | result |
|---|---|---|
| POST /chats/{chat}/polls | actor,title,options:string[],multiple,public_votes,duration_seconds | 201 Poll + message_id; permission 36/57 |
| GET /chats/{chat}/polls/{id} | none | Poll/results; permission 12 + readable message |
| POST /chats/{chat}/polls/{id}/close | actor; If-Match | Poll close receipt; permission 37/58 |
| PUT /chats/{chat}/polls/{id}/vote | actor:user, option_ids[]; If-Match | {poll_id,own_option_ids,revision}; permission 59 |
starting games without joining
GET /games lists currently playable published games and their public start-option schema for installations with bot.games.start. POST /chats/{chat}/games accepts game_id and validated options and returns {game_session_id,chat_id,game_id,status,message_id,player_count}. starting a game emits one attributed invitation and honors normal invite/mute rules. without an active call, create a lobby with zero players; the installer is not silently joined. with an active call, apply the same eligible-human autojoin policy as a normal game start. exclude all bot participants and enforce the game’s human capacity.
game lifecycle
the first human to join a zero-player lobby becomes host under the normal game rules. preserve a pending lobby before invoking game rules that require a player; initialize those rules when the first eligible human joins. empty lobbies expire after 10 minutes and create no score/save entries. if a live game already exists, return 409 game_already_active with its ID only when visible; never replace it. the API offers no player join, input, signal, state projection, save, scoring or game-stop route for bots. a bot that launches games cannot inspect hidden game state or impersonate a human player through another permission.