Quanta Bot API

Build bots for Quanta Messenger. Bots can receive messages, respond to commands, send rich content, and interact with users through inline buttons and callbacks.

Base URL: https://arkonova.network/api/v1/bot

Authentication

There are two types of authentication:

Owner auth (JWT) — used for bot management (register, delete, list). Send your user JWT token in the Authorization: Bearer <token> header.
Bot auth (API Key) — used for bot operations (send messages, get updates). Send the bot's API key in the X-Bot-Token: <api_key> header.

Quick Start

1. Register your bot via the Quanta messenger UI or the API. You'll receive an API key.

2. Use the API key to poll for updates and send messages:

Python
import requests, time

API = "https://arkonova.network/api/v1/bot"
TOKEN = "bot_your_api_key_here"
HEADERS = {"X-Bot-Token": TOKEN}

while True:
    r = requests.get(f"{API}/updates?timeout=30", headers=HEADERS)
    for update in r.json().get("updates", []):
        payload = update["payload"]
        chat_id = payload.get("chat_id")
        text = payload.get("content", "")

        if text.startswith("/start"):
            requests.post(f"{API}/send-message", headers=HEADERS,
                json={"chat_id": chat_id, "content": "Hello! I'm your bot."})

Register Bot

POST /api/v1/bot/register

Parameter	Type	Description
name	string	Bot name (required)
description	string	Bot description
avatar	string	URL or base64 avatar
commands	array	Array of `{command, description}`
permissions	array	Permissions: `read_messages`, `send_messages`

Response
{
  "bot": {
    "id": "uuid",
    "name": "MyBot",
    "description": "...",
    "is_active": true,
    "commands": [{"command": "start", "description": "Start bot"}]
  },
  "api_key": "bot_abc123..."  // Save this! Only shown once.
}

The API key is only returned once. Store it securely.

List My Bots

GET /api/v1/bot/my-bots

List all bots owned by you. Requires JWT auth.

Delete Bot

DELETE /api/v1/bot/delete/<bot_id>

Delete a bot. Requires JWT auth. You must be the bot owner.

Get Bot Info

GET /api/v1/bot/me

Returns information about the bot. Requires bot token auth.

Get Updates (Long-Polling)

GET /api/v1/bot/updates

Wait for new updates (messages, commands, callbacks). Uses long-polling with a configurable timeout.

Query Param	Type	Description
timeout	int	Long-poll timeout in seconds (default: 30)
limit	int	Max updates to return (default: 100)

Response
{
  "updates": [
    {
      "id": "uuid",
      "type": "message",
      "payload": {
        "message_id": "uuid",
        "chat_id": "uuid",
        "user_id": "uuid",
        "username": "john",
        "content": "/start",
        "is_command": true,
        "command": "start"
      },
      "created_at": "2026-02-19T12:00:00"
    }
  ]
}

Send Message

POST /api/v1/bot/send-message

Parameter	Type	Description
chat_id	string	Target chat UUID (required)
content	string	Message text (required)
payload	object	Extra data (buttons, formatting, etc.)

Example — Inline Buttons
{
  "chat_id": "uuid",
  "content": "Choose an option:",
  "payload": {
    "is_bot": true,
    "buttons": [
      [{"text": "Option A", "callback_data": "opt_a"}],
      [{"text": "Option B", "callback_data": "opt_b"}],
      [{"text": "Visit Site", "url": "https://arkonova.network"}]
    ]
  }
}

Set Commands

POST /api/v1/bot/set-commands

Replace all bot commands. Users will see these in the command menu.

Body
{
  "commands": [
    {"command": "start", "description": "Start the bot"},
    {"command": "help", "description": "Show help"},
    {"command": "settings", "description": "Open settings"}
  ]
}

Webhooks

Instead of long-polling, you can receive updates via webhook.

Set Webhook

PUT /api/v1/bot/webhook

Parameter	Type	Description
url	string	HTTPS URL to receive updates (required)
secret	string	Webhook secret for signature verification (auto-generated if omitted)

Remove Webhook

DELETE /api/v1/bot/webhook

Answer Callback

POST /api/v1/bot/answer-callback

Respond to an inline button press from a user.

Parameter	Type	Description
callback_id	string	Callback query ID from the update
text	string	Text to show to the user
chat_id	string	Chat to send a response to
message_content	string	Optional: edit the original message text

Message Payload Format

The payload field in messages can contain:

Key	Type	Description
is_bot	bool	Always `true` for bot messages
buttons	array[][]	Rows of inline buttons. Each button: `{text, callback_data}` or `{text, url}`
nonce	string	E2E encryption nonce (if message is encrypted)

Error Responses

All errors return JSON with an error field:

Status	Meaning
400	Bad request (missing parameters)
401	Authentication failed (invalid or missing token)
403	Forbidden (bot not a member of the chat)
404	Not found (bot or resource doesn't exist)

Error Response
{"error": "chat_id and content are required"}

Need help? Join our developer chat.

Open Quanta Messenger