← Back to Qwing Bots

Your own bot on Qwing

A bot is a Qwing contact that answers by itself. People write to it like to a friend; your program on your own server reads the message and replies. The chat stays end-to-end encrypted, so Qwing cannot read it.

Ideas

What people build

  • Support deskCustomers write to your shop's bot; it answers common questions and takes orders.
  • AlertsYour server, website or smart home sends you a message when something happens.
  • Info on demandWeather, timetables, prices: someone writes /weather Vilnius and gets the answer.
  • Menus and pollsReplies with tappable buttons, so people pick an option instead of typing.

What it can do

A bot today can

  • Read messages sent to itOnly the ones people send to the bot. It sees no other chat.
  • Reply with textAny answer your program decides on.
  • Show buttonsTappable choices under a reply; the bot learns which one was tapped.
  • Have a profileA name, a @username, a description and an avatar, set in the app.
STEP 1

Create the bot in the app

Qwing → Settings → My Bots → Create. Pick a name and a @username. Qwing then shows 24 words once: they are the bot's key. Write them down.

STEP 2

Run its program

A developer puts the 24 words into the Qwing bot SDK, writes what the bot should answer, and starts it on a server. From then on the bot is online and replies.

Manage

Looking after your bot

In Settings → My Bots you can change the bot's name, description and avatar at any time. Its program keeps running on your server.

The 24 words are the bot. Whoever has them controls it, and Qwing never sees them, so they cannot be recovered. Lost them? Create a new bot. Revoke in My Bots switches the bot off for good; it cannot be undone.

For developers

How it works underneath

A bot is a normal Qwing account controlled from code. It has its own hybrid identity (Ed25519 + ML-DSA-87) and its own sessions (X25519 + ML-KEM-1024), exactly like a person's. There is no server-side bot API: the server relays ciphertext, and your bot process decrypts locally with keys derived from its 24 words.

Language Rust 1.91+ Runtime tokio async Crypto X25519 + ML-KEM-1024 · Ed25519 + ML-DSA-87 Hosting your own server

Quickstart

Run the SDK

The SDK is a small self-hostable Rust crate. Give it the token, register your handlers, and call run(). It connects, publishes prekeys, and polls for messages until it is stopped.

Not published yet. The SDK is not on crates.io or in a public repository today. This page documents its API as it stands.
use qwing_bot_sdk::BotClient;

#[tokio::main]
async fn main() -> qwing_bot_sdk::Result<()> {
    let token = std::env::var("BOT_TOKEN").expect("set BOT_TOKEN");
    let mut builder = BotClient::from_token(&token).with_data_dir("./qwing-echo-data");
    if let Ok(url) = std::env::var("BOT_BACKEND") { builder = builder.with_backend(&url); }
    if let Ok(proxy) = std::env::var("BOT_PROXY") { builder = builder.with_proxy(&proxy); }
    let mut bot = builder.connect().await?;   // derives identity, publishes prekeys

    bot.on_message(|msg, ctx| async move {
        match msg.text.as_str() {
            "/start" => ctx.reply("Hi! Send me anything and I'll echo it.").await,
            other  => ctx.reply(&format!("echo: {other}")).await,
        }
    });

    bot.run().await   // polls until stopped
}

Set the token and the API endpoint in the environment:

# liboqs must be on the library path at build and run time
export BOT_TOKEN="word1 word2 … word24"
export BOT_BACKEND="https://api.quantumwing.io/api/v1"
cargo run --release
Optional BOT_PROXY: route over Tor / SOCKS5 Data dir ./qwing-echo-data: session state at rest

Handlers

Commands & replies

There is no fixed command set. You decide what the bot understands inside on_message by matching on msg.text. Commands are just messages that start with / by convention. The context object gives you the reply primitives:

  • ctx.reply(text)Send a plain text reply to the user who messaged the bot.
  • ctx.reply_with_buttons(text, rows)Reply with tappable inline buttons; each carries a callback payload.
  • bot.on_button(cb)Handle a button tap. cb.data is the payload you attached.
  • msg.textThe decrypted inbound text. Match it to route /start, /help, or anything you define.
bot.on_message(|msg, ctx| async move {
    match msg.text.as_str() {
        "/start"   => ctx.reply("Welcome. Try /menu").await,
        "/menu"    => ctx.reply_with_buttons("Pick one:",
                        &[&[("Weather", "pick:weather"), ("News", "pick:news")]]).await,
        _          => ctx.reply("Unknown command. Try /start").await,
    }
});
bot.on_button(|cb, ctx| async move {
    ctx.reply(&format!("You picked {}", cb.data)).await
});

Rules

One token, one instance

Run exactly one process per token. The bot holds a single-instance lock; two processes on the same token would fork the ratchet and permanently break decryption for the people it talks to. If you redeploy, stop the old instance first, and keep the bot's data directory with it. That is where its session state lives.

Privacy

What the server sees

The same as for any Qwing chat: no message content. Messages between a user and your bot are end-to-end encrypted with hybrid (classical + post-quantum) cryptography; the server relays ciphertext and cannot read it. Your bot is the other end of that encryption, so it naturally sees the messages sent to it, and nothing else. It has no window into any other conversation. As with any chat, the server can work out who is talking to your bot (see the Privacy Policy).

Ready? Create the bot in the app, then give its 24 words to the SDK.