Docs

↑ ↓ to move · Enter to open · Esc to close

Get started
Get started

Bots

Create a bot in Bot Studio, get its token, and run it with the @tacenza/bot SDK for Node.js. How bots handle encryption and privacy in groups.

Updated 3 min read

A bot in TACENZA Chat is an account that replies automatically. It has its own keys and takes part in end-to-end encryption like any other member, so the server can’t read what’s sent to it – but whoever runs the bot can. You create a bot in Bot Studio in the app, then run it on your own machine or server with the @tacenza/bot SDK for Node.js.

Create a bot

  1. Choose New › Bot Studio.
  2. Enter a Bot username. It must end in “bot”, for example weather_bot, and follow the usual username rules.
  3. Add a Description.
  4. Under Commands, add one per line as /command = description. Commands are public and shown in the command menu.
  5. Choose Create bot.
  6. Copy the token. It’s shown once – keep it secret.

Your device makes the bot’s keys and signs it up. The server stores only a hash of the token.

Warning

Anyone with the token can run your bot and read what’s sent to it. If a token leaks, choose Revoke token in Bot Studio: the old token stops working and you get a new one.

Manage your bots

Your bots in Bot Studio lists your bots and how many are active.

  • Switch off / Switch on – a switched-off bot stops working until you switch it on.
  • Revoke token – replace the token.
  • Delete – the bot leaves all its chats and its token stops working. This can’t be undone.

Your plan sets how many bots can be active: 1 on Free, 3 on Plus and 10 on Pro.

Run a bot with the SDK

The @tacenza/bot SDK handles keys, encryption and re-keying for you. This example is from the SDK’s README:

import { Bot } from '@tacenza/bot';

const bot = new Bot(process.env.TACENZA_TOKEN!);
bot.command('start', ctx => ctx.reply(`Hi ${ctx.from.name}!`));
bot.command('roll', ctx => ctx.reply(`🎲 ${1 + Math.floor(Math.random() * 6)}`));
bot.on('message', ctx => ctx.reply(`You said: ${ctx.text}`));
await bot.start(); // long polling; or bot.webhook({ port: 8080, url: 'https://mybot.example/tacenza' })
  • Long polling or webhooks. bot.start() polls for updates. With bot.webhook(), the URL must be a public https:// address on port 443; put a TLS proxy in front of your port. The server never calls private or local addresses.
  • Options. baseUrl (default https://api.tacenza.app), statePath, privacyOff and log.
  • State. Pinned keys and the update position are saved to statePath, encrypted with the token secret.
  • Re-keying and retries. Stale conversations get new keys automatically, and conflicts are retried.

Privacy and bots

  • Whoever runs a bot can read what’s sent to it. The app shows a bot badge everywhere, so people know.
  • Privacy mode. In groups, a bot only gets messages that start with /. You can turn this off in the SDK with privacyOff: true.
  • Protected chats. Bots can’t forward or export photos from protected chats.
  • The server stays blind. A bot holds its own keys, so the server still sees only ciphertext. It knows which account created a bot.

Bot API

The SDK talks to the Bot API at https://api.tacenza.app/bot/v1 with an Authorization: Bot <token> header. The API only ever carries ciphertext; the SDK does the encryption. The server limits how fast a bot can send, and plans with more capacity get higher bot limits.

If your bot doesn’t reply

  1. Check that the bot is switched on in Bot Studio.
  2. In a group, check that the message starts with /, or turn privacy mode off.
  3. Check that the token is current. If you revoked it, use the new one.
  4. For webhooks, check that the address is public, uses https:// and port 443.