Bot API

The OSHI Bot API lets you create bots that can send messages to groups and channels, similar to Telegram's Bot API. Bots are created from the OSHI app and controlled programmatically via HTTP endpoints.

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

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.

List all registered bots with stats.

curlcurl https://oshi-messenger.com/api/bot/list

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

# List all bots on server
python oshi_bot.py list

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)

OSHI supports 4 bot types, each designed for different use cases:

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")