Bot API

The OSHI Bot API lets you build bots that both send and receive. A bot registers commands, polls getUpdates for the commands and button taps addressed to it, replies with inline keyboards, and can open a Mini App — the same shapes as Telegram's Bot API, so existing muscle memory transfers.

The one place OSHI deliberately differs is what a bot is allowed to see. Group conversation never reaches a bot, and that is not a setting. Read that section first — it decides which bots are buildable here.

A bot receives an update in exactly two situations, and no others:

1. A user sends a slash command addressed to your bot — /weather Paris
2. A user taps a button your bot itself rendered — an inline keyboard callback

Ordinary group conversation never reaches your bot

Not filtered, not redacted, not rate-limited — absent. Messages between members are end-to-end encrypted; the server relays ciphertext it cannot read. Forwarding group chat to a bot is not a feature that was left switched off, it is a thing the server is not able to do.

What this rules in and out

Follow these 4 steps to create a bot and start sending messages:

Your bot receives work by long-polling getUpdates. Updates are held in a per-bot queue on the server and acknowledged by offset, exactly like Telegram: you confirm you have handled everything up to update_id by asking for update_id + 1 next time.

Update shapes

Each update carries update_id plus exactly one of message or callback_query.

message.text always begins with / — a non-command message is rejected at dispatch and never becomes an update. See What Bots Can See.

Polling loop

bash# First call: no offset, take whatever is queued
curl "https://oshi-messenger.com/api/bot/getUpdates?token=YOUR_BOT_TOKEN&timeout=50"

# Then acknowledge by asking for the next id
curl "https://oshi-messenger.com/api/bot/getUpdates?token=YOUR_BOT_TOKEN&offset=3&timeout=50"

Acknowledge a button tap. Telegram's answerCallbackQuery. Call it for every callback_query you receive, even when you have nothing to say: it marks the callback answered server-side, and it is the only way to show the user a toast.

A callback id belongs to the bot it was issued for. Answering another bot's callback returns 404 Unknown callback_query_id.

Called by the OSHI client, not by your bot. This is the endpoint the app hits when a user invokes a bot, and it is the only thing that creates an update. It is documented so the model is inspectable — if you are writing a bot you will never call it.

The 400 on text that does not start with / is the privacy rule expressed in code: there is no request shape that turns an ordinary message into an update.

Pass replyMarkup to /api/bot/send to attach buttons to a message. The shape mirrors Telegram's.

json{
  "inline_keyboard": [
    [ { "text": "Buy",  "callback_data": "buy:sku-42" },
      { "text": "Docs", "url": "https://example.com/docs" } ],
    [ { "text": "Open Shop", "web_app": { "url": "https://shop.example.com/app" } } ]
  ]
}

Button types

Limits

Sending one

bashcurl -X POST https://oshi-messenger.com/api/bot/send \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_BOT_TOKEN",
    "groupId": "GROUP_UUID",
    "content": "What would you like to do?",
    "replyMarkup": {
      "inline_keyboard": [
        [ { "text": "Buy", "callback_data": "buy:sku-42" } ],
        [ { "text": "Open Shop", "web_app": { "url": "https://shop.example.com/app" } } ]
      ]
    }
  }'

A Mini App is your own web page, opened inside OSHI from a web_app button. OSHI hands it a signed initData string that identifies the user who opened it, so your page can log them in without asking them to sign in again.

1. Register the Mini App

bashcurl -X POST https://oshi-messenger.com/api/bot/setMiniApp \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_BOT_TOKEN","url":"https://shop.example.com/app","name":"Shop"}'

# read it back
curl "https://oshi-messenger.com/api/bot/getMiniApp?token=YOUR_BOT_TOKEN"

This is stored against your bot and survives a server restart. Set it once.

2. The client asks for a session

The OSHI app calls this when the user taps your web_app button. It returns the URL to open plus the signed initData to hand to the page. Your bot token stays on the server; the Mini App never sees it.

Like /dispatch, it accepts either the bot's token (owner) or its public botId (any member of a group the bot serves, proving themselves with userPublicKey; non-members get 403). Bot authors do not call this — the app does.

3. The initData scheme

Identical to Telegram's Web App algorithm, with the same field names:

1. Take every field except hash as key=value
2. Sort those lines by key and join them with \n — the data-check string
3. secret = HMAC_SHA256(key="WebAppData", message=bot_token)
4. hash = HMAC_SHA256(key=secret, message=data_check_string), hex encoded

initData expires 24 hours after auth_date. Expired data fails validation even when the signature is perfect.

4. Validate it — server-side, every time

bashcurl -X POST https://oshi-messenger.com/api/bot/miniapp/validate \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_BOT_TOKEN","initData":"<the raw string, unmodified>"}'

A bad signature, a tampered field, an expired auth_date, or initData signed for a different bot all return 401. Pass the string through byte for byte — re-encoding or re-ordering the parameters changes the data-check string and the signature will not match.

One runnable script that exercises the whole surface: it declares a command, long-polls for updates, answers with an inline keyboard, handles the button tap, and offers a Mini App. Only requests is needed.

python#!/usr/bin/env python3
"""A complete OSHI bot: command -> inline keyboard -> callback -> Mini App."""
import requests, time

API      = "https://oshi-messenger.com"
TOKEN    = "YOUR_BOT_TOKEN"
GROUP    = "YOUR_GROUP_UUID"
MINI_APP = "https://shop.example.com/app"


def api(method, path, **kw):
    r = requests.request(method, API + path, timeout=70, **kw)
    r.raise_for_status()
    return r.json()


# --- one-time setup -------------------------------------------------------
# Both of these persist on the server; you do not need to repeat them at every
# start-up, but doing so is harmless and keeps the bot self-describing.
api("POST", "/api/bot/setMyCommands", json={
    "token": TOKEN,
    "commands": [{"command": "shop", "description": "Browse the catalogue"}],
})
api("POST", "/api/bot/setMiniApp", json={
    "token": TOKEN, "url": MINI_APP, "name": "Shop",
})


# --- handlers -------------------------------------------------------------
def send(text, markup=None):
    body = {"token": TOKEN, "groupId": GROUP, "content": text}
    if markup:
        body["replyMarkup"] = markup
    return api("POST", "/api/bot/send", json=body)


def on_command(msg):
    text = msg.get("text", "")
    # The text is addressed to this bot; strip any /command@botname form.
    cmd = text.split()[0].lstrip("/").split("@")[0].lower()

    if cmd == "shop":
        send("What would you like to do?", markup={"inline_keyboard": [
            [{"text": "Today's deal", "callback_data": "deal"},
             {"text": "Catalogue", "url": "https://shop.example.com/catalogue"}],
            [{"text": "Open Shop", "web_app": {"url": MINI_APP}}],
        ]})
    else:
        # Unknown command. Worth answering: the user typed it deliberately.
        send(f"I don't know /{cmd}. Try /shop")


def on_callback(cb):
    # ALWAYS answer, even with no text: this clears the pending state on the
    # button. toPublicKey is what makes the toast visible - without it the call
    # succeeds and the user sees nothing.
    api("POST", "/api/bot/answerCallback", json={
        "token": TOKEN,
        "callbackQueryId": cb["id"],
        "text": "Fetching today's deal...",
        "toPublicKey": cb.get("from", {}).get("public_key"),
    })

    if cb.get("data") == "deal":
        send("Today: 20% off everything.", markup={"inline_keyboard": [
            [{"text": "Open Shop", "web_app": {"url": MINI_APP}}],
        ]})


# --- the polling loop -----------------------------------------------------
def main():
    offset = 0   # 0 = "give me whatever is queued"; never invent a value
    while True:
        try:
            # timeout=50 is a LONG POLL: the server holds the connection until
            # an update arrives or 50s pass. It is not a delay - it is how you
            # get instant delivery without hammering the API.
            params = {"token": TOKEN, "timeout": 50, "limit": 100}
            if offset:
                params["offset"] = offset
            updates = api("GET", "/api/bot/getUpdates", params=params)["result"]
        except requests.RequestException as e:
            print("poll failed, retrying:", e)
            time.sleep(5)
            continue

        for u in updates:
            # Advance the offset BEFORE handling, and outside the try below, so
            # one poisonous update cannot wedge the loop redelivering forever.
            offset = u["update_id"] + 1
            try:
                if "message" in u:
                    on_command(u["message"])
                elif "callback_query" in u:
                    on_callback(u["callback_query"])
            except Exception as e:
                print("handler error on update", u["update_id"], e)


if __name__ == "__main__":
    main()

The Mini App backend

The page opened by the web_app button receives initData. Here is the only correct way to use it — validated server-side, never parsed and trusted in the browser:

pythonfrom flask import Flask, request, jsonify
import requests

app = Flask(__name__)
API   = "https://oshi-messenger.com"
TOKEN = "YOUR_BOT_TOKEN"     # server-side ONLY. Never sent to the browser.


def current_user(init_data: str):
    """Return the verified user, or None. The ONLY source of identity."""
    r = requests.post(f"{API}/api/bot/miniapp/validate",
                      json={"token": TOKEN, "initData": init_data}, timeout=10)
    if r.status_code != 200:
        return None                      # bad signature, tampered, or expired
    return r.json()["data"]["user_public_key"]


@app.post("/api/orders")
def create_order():
    # The front end sends the raw initData string it was handed, UNMODIFIED.
    user = current_user(request.headers.get("X-Init-Data", ""))
    if not user:
        return jsonify(error="unauthenticated"), 401

    # `user` is now trustworthy. Anything the browser claimed about identity
    # is not, and is ignored.
    return jsonify(ok=True, buyer=user)

javascript// WRONG - this is an authentication bypass, not a login.
const params = new URLSearchParams(initData);
const user = params.get("user_public_key");   // attacker edits this to anyone
showDashboardFor(user);

Send a message to a group via bot token. This is the primary endpoint for bot messaging.

Request Body

Request

curlcurl -X POST https://oshi-messenger.com/api/bot/send \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_BOT_TOKEN",
    "groupId": "GROUP_UUID",
    "content": "Hello from my bot"
  }'

Response

Register a bot with the server. Automatically called by the OSHI app, but can also be called manually for programmatic registration.

Request Body

curlcurl -X POST https://oshi-messenger.com/api/bot/register \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_BOT_TOKEN",
    "botName": "My Alert Bot",
    "ownerPublicKey": "your_public_key",
    "groups": [{
      "id": "group-uuid",
      "name": "Alerts",
      "members": ["member1_key", "member2_key"]
    }]
  }'

Get bot info, stats, and assigned groups.

curlcurl "https://oshi-messenger.com/api/bot/info?token=YOUR_BOT_TOKEN"

Response

Update the bot's group assignments.

Return your own bot and its stats. Requires your bot token — this endpoint no longer lists other people's bots.

curlcurl "https://oshi-messenger.com/api/bot/list?token=YOUR_BOT_TOKEN"

Declare the commands your bot answers to, so users can discover them. Stored against your bot and preserved across server restarts.

A leading / is stripped for you. Names must match [a-z0-9_], 1–32 characters — anything else is a 400 naming the offending command. Descriptions are truncated at 256 characters.

bashcurl -X POST https://oshi-messenger.com/api/bot/setMyCommands \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_BOT_TOKEN",
    "commands": [
      {"command": "/shop",  "description": "Browse the catalogue"},
      {"command": "status", "description": "Service status"}
    ]
  }'

Register the Mini App URL for your bot, or read back what is registered. Also preserved across restarts. Full detail in Mini Apps.

Add a single member to one of the bot's groups, without resending the whole group list.

Adding someone already present is a no-op and still returns 200, with botsUpdated: 0.

Remove a bot from the server registry.

curlcurl -X DELETE "https://oshi-messenger.com/api/bot/unregister?token=YOUR_BOT_TOKEN"

The official Python SDK provides a clean OshiBot class for easy integration. Only requires the requests library.

Installation

bashpip install requests
# Download the SDK
curl -O https://oshi-messenger.com/sdk/oshi_bot.py

Quick Start

pythonfrom oshi_bot import OshiBot

# Initialize with your bot token
bot = OshiBot(token="YOUR_BOT_TOKEN")

# Send a message to a group
result = bot.send("GROUP_UUID", "Hello from Python!")
print(f"Delivered to {result['delivered']} members")

# Get bot info
info = bot.info()
print(f"Bot: {info['bot']['botName']}")
print(f"Messages sent: {info['bot']['stats']['messagesSent']}")

# Send to all assigned groups
results = bot.send_to_all_groups("Broadcast message!")

# Get groups list
groups = bot.get_groups()
for g in groups:
    print(f"  {g['name']} ({g['memberCount']} members)")

Sending Media

python# Send an image with caption
bot.send_image("GROUP_UUID", "/path/to/chart.png", caption="Daily chart")

# Send a document
bot.send_document("GROUP_UUID", "/path/to/report.pdf", caption="Q4 Report")

# Send any file (auto-detects type from extension)
bot.send_file("GROUP_UUID", "/path/to/data.csv")

# Low-level: send raw base64 media
import base64
with open("photo.jpg", "rb") as f:
    data = base64.b64encode(f.read()).decode()
bot.send_media("GROUP_UUID", "photo", data, "photo.jpg", content="Check this!")

Command Line

bash# Send a message
python oshi_bot.py send YOUR_TOKEN GROUP_ID "Hello!"

# Get bot info
python oshi_bot.py info YOUR_TOKEN

# List groups
python oshi_bot.py groups YOUR_TOKEN

# Check stats
python oshi_bot.py stats YOUR_TOKEN

# Show your own bot (this no longer lists other people's bots)
python oshi_bot.py list YOUR_TOKEN

Bots can send images, videos, audio, and documents alongside text messages. Media is sent as Base64-encoded data within the JSON payload.

Supported Media Types

How It Works

1. Read the file and encode it as Base64
2. Include mediaType, mediaData, and mediaFileName in the request body
3. The content field serves as an optional caption
4. OSHI clients render the media inline with the caption

All messages in OSHI benefit from the same encryption pipeline used for user messages. Bot messages are encrypted before being stored on IPFS.

How Bot Messages Are Secured

1. TLS in transit — Bot sends message via HTTPS to /api/bot/send
2. Server queues — Message is queued for each group member
3. AES-256-GCM encryption — OSHI client encrypts the message with a derived group key
4. IPFS storage — Encrypted payload is pinned to IPFS via Pinata for decentralized delivery
5. Client decryption — Only group members can derive the key and decrypt

Encrypted Envelope (v2)

Messages stored on IPFS are wrapped in an encrypted envelope. Only the version number and a short routing hint are visible:

Hidden inside the encrypted envelope:

• Message content, sender key, recipient keys
• Timestamp, group ID, message chain index
• Media type and attachment data

The OSHI SDK includes an OshiMoltBotBridge class that acts as a transport/output plugin for the MoltBot multi-platform bot framework.

pythonfrom oshi_bot import OshiMoltBotBridge

# Initialize bridge
bridge = OshiMoltBotBridge(
    oshi_token="YOUR_BOT_TOKEN",
    default_group="GROUP_UUID"
)

# Send to default group
bridge.send("Hello from MoltBot!")

# Send to specific group
bridge.send("Alert!", group_id="other-group-uuid")

# Broadcast to all groups
bridge.broadcast("System maintenance in 5 minutes")

# Use as MoltBot output plugin
class MyMoltBot:
    def __init__(self):
        self.outputs = [bridge]

    def on_event(self, event):
        message = f"Event: {event['type']} - {event['data']}"
        for output in self.outputs:
            output.send(message)

Four shapes that work well on OSHI. Each is driven by a user acting deliberately, or by your own schedule — never by reading group conversation:

Python Error Handling

pythonfrom oshi_bot import OshiBot, OshiAuthError, OshiGroupError, OshiRateLimitError

bot = OshiBot(token="YOUR_TOKEN")

try:
    bot.send("GROUP_ID", "Hello!")
except OshiAuthError:
    print("Invalid token - register the bot first")
except OshiGroupError:
    print("Bot not assigned to this group")
except OshiRateLimitError:
    print("Slow down - rate limit exceeded")