This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Configuration file reference

This document describes the structure and semantics of the Delta bot configuration file. The configuration is defined in YAML and deserialized into a set of Rust structures that control the bot’s behavior, integrations, and messaging logic.

Overview

The root configuration object (Configuration) defines global settings and collections of hooks, commands, and message rules. Most fields support defaults and can be omitted unless explicitly required.

Root Configuration

data_dir: ".data"
display_name: "Delta Fastbot"
avatar: null
webhooks: {}
raw_messages: []
postgres_hooks: []
custom_commands: {}
translations: {}
listen_address: "0.0.0.0:8080"
qr: "..."

Fields

• data_dir (string, default: ".data") - directory used for persistent storage,
• display_name (string, default: "Delta Fastbot") - public display name of the bot,
• avatar (string, optional) - path to the bot avatar,
• translations - key-value map for message localization,
• listen_address (string, default: "0.0.0.0:8080") - address and port where the bot listens for incoming requests,
• qr (string, required) - mandatory field used for authentication and initialization.

The qr field must contain a valid Delta Chat account link (QR payload), which is typically obtained from the homepage of a Delta Chat-compatible mail server.

How to Obtain the qr

1. Open the homepage of your chosen Delta Chat server (for example, https://chatmail.fossware.org/),
2. Locate the button labeled: Get a chatmail.fossware.org chat profile,
3. Copy the link associated with that button; in this specific case, the resulting value is qr: "dcaccount:https://chatmail.fossware.org/new"

Translations

The translations field is a key-value map used to localize user-facing text within the bot. It allows you to override default strings and provide custom wording, typically in a specific language. Every string not found in this map will default to the english version.

An example, in italian, is:

translations:
  available_commands: Comandi
  admin_commands: Comandi admin
  admin_token: Consuma un token per diventare admin
  info: Ottieni informazioni riguardo il bot
  support: Contatta un@ admin
  broadcast: Invia un messaggio a ogni utente conosciut@
  new_admin_token: Genera un nuovo token per diventare admin
  set_welcome_message: Aggiorna il messaggio di benvenuto
  welcome: Mostra il messaggio di benvenuto

The following keys are used internally to build structured messages shown to users:

• available_commands
• admin_commands

These values act as labels or section headers when the bot generates command lists or help messages.

All other keys in the map are interpreted as command identifiers. The key must match the exact name of a registered command, and the value is used as its human-readable description.

For example:

• info → description for the /info command
• support → description for the /support command
• broadcast → description for the /broadcast command

These descriptions are displayed when showing the help command.

Event Hooks and Commands Configuration

This section of the configuration defines how the bot reacts to external events (database changes and HTTP requests) and how users can trigger custom behavior via commands.

All sections are optional and can be omitted if not needed.

PostgreSQL Hooks

The postgres_hooks array defines listeners for database events. Each entry connects to a PostgreSQL instance, watches a specific table, and converts matching events into Delta Chat messages.

postgres_hooks:
  - event: INSERT
    columns:
      - name
      - image
    channel_name: Channel
    attachment: image
    host: ...
    user: postgres
    password: postgres
    database: database
    table: beautiful_table
    template: "New column inserted: {name}"
    parse_chatid: true
    chats:
      - ...

Behavior

When the configured event occurs (e.g. a new row is inserted), the bot:

1. Receives the event from the database,
2. Extracts the specified columns from the affected row,
3. Renders the template using those values,
4. Sends the resulting message to the configured chats or channel.

Key Concepts

Event filtering

The event field determines which database operation triggers the hook. If omitted, it defaults to INSERT.

Column extraction

The columns list defines which fields are available inside the template. These are referenced using {column_name} syntax.

Message templating

The template is a string where placeholders are replaced with actual database values at runtime.

Channel publishing

If channel_name is set, the bot creates (or reuses) a channel and sends messages there. This allows multiple hooks to aggregate into a single stream.

Attachments

The attachment field refers to a column containing an URL (e.g. an image). If present, it will be downloaded and included in the message.

Dynamic chat routing

If parse_chatid is true, the bot will attempt to extract a chat ID from the event data instead of relying only on the static chats list.

Static recipients

The chats field defines explicit destinations using Delta Chat QR identifiers.

Database connection

Standard PostgreSQL connection parameters are required (host, user, password, database, and table).

Webhooks

The webhooks section defines HTTP endpoints that the bot exposes. Each entry corresponds to a route that accepts incoming JSON payloads and converts them into messages.

webhooks:
  hook_name:
    template: "New event received: {name}"
    channel_name: Channel
    attachment: image
    parse_chatid: true
    chats:
      - ...

Behavior

Each webhook is available at:

{listen_address}/webhook/{hook_name}

When a request is received:

1. The JSON payload is parsed,
2. Fields are interpolated into the template,
3. A message is generated and delivered.

Key Concepts

Template interpolation

JSON fields are referenced using {field_name} syntax.

Shared delivery logic

Fields like channel_name, attachment, parse_chatid, and chats behave exactly as in other kind of hooks.

Loose schema

The webhook does not enforce a strict payload structure. Any JSON field can be used in the template.

Custom Commands

The custom_commands section defines commands that users can invoke directly in private chats using the /command_name syntax.

custom_commands:
  command_name:
    include_payload: true
    include_chatid: false
    url: "localhost:8080/hook"
    description: "Test command"

Behavior

When a user sends /command_name:

1. The bot issues an HTTP POST request to the configured url,
2. Optionally includes structured data about the message,
3. The external service processes the request and returns a response (if applicable).

Key Concepts

Command trigger

The command name is defined by the key (command_name) and invoked with a / prefix.

Payload control

• include_payload: includes message metadata (text, sender, etc.).
• include_chatid: includes the chat identifier, useful for routing responses.

External integration

This mechanism allows integration with APIs, automation tools, or workflow engines.

Raw Messages

The raw_messages section defines message forwarding and external delivery rules. It allows the bot to intercept incoming messages from specific chats, optionally transform them, and then forward them to other chats and/or external HTTP endpoints.

raw_messages:
  - chats:
      - ...
    template: "{body}"
    hook: https://telebulbo.sinistraverso.org/api/integrations/chat/send
    forward_to:
      - ...
    bearer_auth: "..."

Behavior

For each entry:

1. The bot monitors the specified chats.
2. When a new message is received the message content is injected into the template and the resulting output is:
   • Forwarded to all forward_to chats (if any)
   • Sent as a POST request to the hook endpoint

Available fields for templating are:

• user, the display name of the message's author,
• body, the message text.

Fields

• chats (array, required) - source chats to listen to. Each entry must be a valid Delta Chat QR link,
• template (string, required) - defines how the outgoing message is constructed,
• hook (string, optional) - HTTP endpoint that will receive the message via POST request in JSON format, with only a field body, that contains the template output,
• forward_to (array, optional) - list of destination chats where the message will be forwarded,
• bearer_auth (string, optional) - bearer token used for authenticating the HTTP request, if set, the bot includes an Authorization: Bearer header.