GROM Bot API

Appearance

Getting a token ​

Every request you make is authenticated by a token in the URL path. This page is how you get one — the flow that actually works today, not the one the rest of the internet describes.

This works now

POST /newbot issues a real, working token. The full chain — account login → /newbot → getMe → sendMessage — is verified end to end against the running gateway. It is still 0.1-draft, so the surface may change; design against it, but do not pin production to it yet. Implementation status.

On Telegram you'd chat with a bot; here you POST ​

Telegram mints tokens by talking to @BotFather. GROM's equivalent is @GromCore, and the conversational bot is not up yet — so today you create a bot over HTTP instead. The same account that owns the bot authorises its creation; when @GromCore and the BotFather-style web dashboard arrive, they will sit on top of this exact call, not replace it.

1. Log into your GROM account ​

A bot is owned by a GROM user account, so you authenticate as yourself first. Logging in returns an account access token — this is your token, not the bot's. (In the app this happens for you; over the API it is the ordinary OTP login.)

bash
API=https://api.casinoplaneta.info

# Request a one-time code for your number.
curl -X POST $API/api/v1/auth/otp/request \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+998900000000","channel":"sms"}'
# -> {"data":{"otp_id":"…","demo":true,"debug_code":"123456"}}   (demo returns the code)

# Exchange the code for tokens. device_id must be a real UUID.
curl -X POST $API/api/v1/auth/otp/verify \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+998900000000","otp_id":"<otp_id>","code":"<code>",
       "device_id":"11111111-2222-3333-4444-555555555555",
       "device_name":"dev","platform":"web"}'
# -> {"data":{"access_token":"<ACCOUNT_TOKEN>","refresh_token":"…","user":{"id":…}}}

The access token is short-lived (15 minutes); refresh it with POST /api/v1/auth/refresh using the refresh token. You only need it for the next step.

2. Create the bot ​

POST /newbot with your account token as a Bearer credential. A name for display, a username ending in bot, and you get the token back — once.

bash
curl -X POST $API/newbot \
  -H "Authorization: Bearer <ACCOUNT_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Weather Bot","username":"myweatherbot"}'
# -> {"ok":true,"result":{"bot_id":24,"username":"myweatherbot",
#                          "token":"24:z8pq2yhA…"}}

Rules the gateway enforces:

  • The username must end in bot (or _bot), case-insensitive, and be globally unique across users and groups/channels.
  • One account may own at most 20 bots (bots_max).
  • The token is generated from a CSPRNG and stored only as an Argon2id hash. The clear token is shown this one time — save it now; it cannot be read back later.

3. Use it ​

The token goes in the path of every call. Confirm it works, then send:

bash
BOT=24:z8pq2yhA…

curl $API/bot$BOT/getMe
# -> {"ok":true,"result":{"id":24,"is_bot":true,"username":"myweatherbot",…}}

curl -X POST $API/bot$BOT/sendMessage \
  -H 'Content-Type: application/json' \
  -d '{"chat_id":<your_user_id>,"text":"hello"}'
# -> {"ok":true,"result":{"message_id":1,…}}

A wrong token answers 401 Unauthorized — a wrong-token reply, not 404, which is how you can tell the gateway is up. From here, your first bot walks the receive-and-reply loop, and the method reference is the full surface.

Keeping the token ​

It is worth repeating, because it is the one mistake that ends badly: the token is the bot. Anyone who reads it can act as you. Keep it in a secret store, never in source control or a browser, and if you even suspect it leaked, re-issue it — revoking cuts every session and webhook for the old token immediately. The security page has the rest.

What isn't here yet ​

  • @GromCore in chat — the conversational /newbot, /setname, /setcommands and the rest of the BotFather command set. The management operations exist today as API methods where one is live (setMyCommands, setMyName, setChatMenuButton, …); the chat front-end for them comes later on this same path.
  • The web dashboard (bot.casinoplaneta.info/dashboard) — a BotFather-style UI. Deferred until the official bots ship.
  • api_id / api_hash for an MTProto client — the developer portal will issue these; it cannot yet.