Python

The Python client, veilmesh-bot. Python 3.9 or later, the standard library only.

pip install veilmesh-bot

An echo bot

from veilmesh_bot import Client

bot = Client.from_token_file("token.json")
bot.set_commands([{"name": "echo", "description": "Repeat the text", "args": "TEXT"}])
bot.skip_old()

for msg in bot.messages():
    if msg.text.strip().lower() == "ping":
        bot.reply(msg, "pong")
    elif msg.text.startswith("/echo "):
        bot.reply(msg, msg.text[6:])

messages() runs forever. While the daemon is away (stopped, restarting) it waits and tries again, from 1 second up to 30; a refused token ends it with an error.

The client

  • Client(token, url="http://127.0.0.1:8471", timeout=30), or Client.from_token_file(path, url) with the raw token or the JSON veilmesh-bot token prints. Only a loopback address is accepted, and the token never appears in repr or errors.
  • me(), groups() — the bot and its groups (Group: id, title, members, closed).
  • messages(wait=30) — incoming group messages (Message: group, id, author, text, sent_at, file, seq).
  • events(wait=0), skip_old() — the raw event stream and its cursor; missed is set when events were lost (the daemon keeps 1000, and restarts number them anew).
  • send(group, text, reply_to=None), reply(msg, text) — the new message's id.
  • send_file(group, path, caption=None) — a file in the daemon's --files-dir.
  • react(group, message, emoji), leave(group).
  • commands(), set_commands(list) — the commands members see on /.

Errors are ApiError with status (0: the daemon is not reachable) and message.

Before the token first goes out, the client checks that the program on the port is the bot (/v1/hello), so a program that took the port gets nothing.

More examples

In examples/ of the clients' repository: a webhook bridge for Alertmanager and other senders, an assistant on Claude, and one on a local model (Ollama or llama.cpp). Read Security before you connect a bot to an AI model.