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 depending on the operation:

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

Header	Used for	Value
Authorization	string	`Bearer <your_jwt_token>` — owner operations
X-Bot-Token	string	`<bot_api_key>` — bot operations

Quick Start

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

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

Python — minimal polling bot

import requests 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. 👋" })

JavaScript (Node.js) — minimal polling bot

Register Bot

POST /api/v1/bot/register

Create a new bot. Returns the bot object and a one-time API key. Requires JWT auth.

Parameter	Type	Description
name	string	Bot display name *required
description	string	Short description shown in the bot profile
avatar	string	URL or base64-encoded avatar image
commands	array	Array of `{"command": "...", "description": "..."}`
permissions	array	`read_messages`, `send_messages`

Response — 200 OK

{ "bot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "MyBot", "description": "A helpful assistant bot", "is_active": true, "commands": [ {"command": "start", "description": "Start the bot"}, {"command": "help", "description": "Show help"} ] }, "api_key": "bot_abc123xyz..." // ⚠ Shown only once — store it securely! }

The api_key is returned only once at registration. Save it immediately — it cannot be retrieved again.

List My Bots

GET /api/v1/bot/my-bots

Returns all bots owned by the authenticated user. Requires JWT auth.

Response — 200 OK

{ "bots": [ { "id": "uuid", "name": "MyBot", "description": "...", "is_active": true, "commands": [...] } ] }

Delete Bot

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

Permanently delete a bot. Requires JWT auth. You must be the bot owner.

Get Bot Info

GET /api/v1/bot/me

Returns profile information about the bot identified by the current X-Bot-Token. Requires bot token auth.

Response — 200 OK

{ "id": "uuid", "name": "MyBot", "description": "A helpful assistant", "is_active": true, "commands": [{"command": "start", "description": "Start"}] }

Get Updates (Long-Polling)

GET /api/v1/bot/updates

Wait for new updates — messages, commands, callback button presses. Uses long-polling: the server holds the connection open until an update arrives or timeout expires.

Query Param	Type	Description
timeout	int	Long-poll wait time in seconds (default: `30`)
limit	int	Max updates per response (default: `100`)

Response — 200 OK

{ "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-20T12:00:00" } ] }

For production use consider Webhooks instead of long-polling to avoid keeping connections open.

Send Message

POST /api/v1/bot/send-message

Send a message to a chat. Supports plain text, inline keyboard buttons, and URL buttons.

Parameter	Type	Description
chat_id	string	Target chat UUID *required
content	string	Message text *required
payload	object	Extra data — inline buttons, formatting

Example — plain text

{ "chat_id": "550e8400-e29b-41d4-a716-446655440000", "content": "Hello! How can I help you?" }

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"}] ] } }

Each row in buttons is an array of button objects. A button can have either callback_data (triggers a callback update) or url (opens a URL in the browser).

Set Commands

POST /api/v1/bot/set-commands

Replace all bot commands. The updated list is shown to users in the command autocomplete menu inside Quanta.

Body

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

Webhooks

Instead of long-polling, register an HTTPS endpoint to receive updates pushed in real time.

Set Webhook

PUT /api/v1/bot/webhook

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

Once set, Arkonova will POST each update as JSON to your url. Verify the request by checking the X-Webhook-Secret header against your secret.

Python — webhook handler (Flask)

from flask import Flask, request, abort app = Flask(__name__) WEBHOOK_SECRET = "your_webhook_secret_here" @app.post("/quanta-webhook") def webhook(): if request.headers.get("X-Webhook-Secret") != WEBHOOK_SECRET: abort(403) update = request.json # handle update... return "", 200

Remove Webhook

DELETE /api/v1/bot/webhook

Remove the registered webhook. The bot reverts to long-polling mode.

Answer Callback

POST /api/v1/bot/answer-callback

Respond to an inline button press. Must be called after receiving a callback type update.

Parameter	Type	Description
callback_id	string	Callback query ID from the update *required
text	string	Notification text shown to the user (toast/alert)
chat_id	string	Chat to send a follow-up message to
message_content	string	Edit the original message text (optional)

Example

{ "callback_id": "uuid-from-update", "text": "You chose Option A!", "chat_id": "uuid", "message_content": "✅ Option A selected." }

Message Payload Format

The payload field attached to outgoing bot messages supports the following keys:

Key	Type	Description
is_bot	bool	Must be `true` for bot messages
buttons	array[][]	2-D array of button rows. Each button: `{"text", "callback_data"}` or `{"text", "url"}`
nonce	string	E2E encryption nonce (if the message uses end-to-end encryption)

Error Responses

All error responses return JSON with an error field and a standard HTTP status code:

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

Error response shape

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

Need help? Join our developer community in Quanta.

Open Quanta Messenger Back to Wiki