QivunaDevelopers

Bots on Qivuna

A bot is a Qivuna account run by your server. People chat with it one to one, and room admins can add it to groups and channels with the rights they choose.

The API in one minute#

Every method is an HTTPS request to https://bots.qivuna.com/v1/<method> with the bot's token in the Authorization header:

curl -s https://bots.qivuna.com/v1/getMe \
  -H "Authorization: Bot $QIVUNA_BOT_TOKEN"
{"ok":true,"result":{"id":7123456789,"is_bot":true,"first_name":"Weather","username":"weather_bot",
 "can_join_groups":true,"can_join_channels":true,"privacy_mode":true,"e2ee_mode":"plain",
 "api_version":"1.0","status":"development","tier":"new"}}

The bot receives updates — messages, button presses, being added to a room — by long polling getUpdates (a webhook option opens later), and answers with methods like sendMessage:

curl -s https://bots.qivuna.com/v1/sendMessage \
  -H "Authorization: Bot $QIVUNA_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 4503600212045337, "text": "Hello!"}'

Where bots can be#

ContextHow the bot takes part
1:1 chat with a plain botServer-readable messages. The app labels the chat: “Messages here are not end-to-end encrypted. Qivuna and the bot's developer can read them.”
1:1 chat with an encrypted botEnd-to-end encrypted to the bot's key. Label: “Only the bot's developer can read what you send it.”
Public groupAdded by an admin with rights (a server grant). Privacy mode decides what it reads.
Channel (public or private)Added by the owner or an admin; receives every post; posts with can_post.
Private group, not yet encryptedA server grant without “read all”. When the group becomes end-to-end encrypted, the grant is suspended at once.
Private group, end-to-end encryptedEncrypted bots only, in addressed mode: the bot receives only what a member explicitly sends to it, and answers privately to that member. It never gets the group's key.
Secret chats and callsNever.

What bots never see#

The app shows every person the same facts on the bot's profile (“What this bot can see”) and in each room's Bots section.

The lifecycle of a bot#

  1. Create it with @qivbot, in the Qivuna app. It starts in development mode: anyone with the link can start it, but it can join only your own small groups and does not appear in search.
  2. Build it against the API with your token.
  3. Publish it from QivBot when it has a description and at least one command. It then appears in search and any admin can add it.
  4. Optionally ask for the blue check.

A bot can be restricted (reads only), suspended or banned for abuse; see Reporting and abuse. Deleting a bot is permanent; its handle stays reserved for 30 days.

Coming from Telegram#

Method names, update shapes and keyboards follow the Telegram Bot API where that made sense. The differences that matter: