Short invite link service & custom username bot for Delta Chat
  • Python 98.4%
  • Shell 1.4%
  • Dockerfile 0.2%
Find a file
2026-10-29 18:15:17 +00:00
.github/workflows v1.14.0: automatic account creation, releases by tag (#3) 2026-10-24 16:28:31 +01:00
tests v1.18.0: keep the claim date as Linked, show contact sync changes as Updated 2026-10-29 18:15:17 +00:00
web v1.18.0: keep the claim date as Linked, show contact sync changes as Updated 2026-10-29 18:15:17 +00:00
.dockerignore feat: initial release of Delta Chat Username Bot (v1.0.0) 2026-07-24 23:49:54 +03:00
.env.example config: set default INVITE_BASE_URL to i.deltachat.id 2026-08-22 00:55:18 +03:00
.gitignore feat: initial release of Delta Chat Username Bot (v1.0.0) 2026-07-24 23:49:54 +03:00
bot.py v1.17.0: core 2.66.0, own address from the self contact 2026-10-28 20:02:21 +00:00
Caddyfile feat: default to deltachat.id with dynamic multi-domain support (v1.6.0) 2026-08-22 00:52:46 +03:00
CHANGELOG.md v1.18.0: keep the claim date as Linked, show contact sync changes as Updated 2026-10-29 18:15:17 +00:00
commands.py v1.18.0: keep the claim date as Linked, show contact sync changes as Updated 2026-10-29 18:15:17 +00:00
contact_sync.py v1.16.1: fingerprint parsing safe against display names, ready for core 2.66; pin core 2.65.0 2026-10-28 17:11:31 +00:00
database.py v1.18.0: keep the claim date as Linked, show contact sync changes as Updated 2026-10-29 18:15:17 +00:00
dc_fingerprint.py v1.17.0: core 2.66.0, own address from the self contact 2026-10-28 20:02:21 +00:00
dc_helpers.py v1.16.1: fingerprint parsing safe against display names, ready for core 2.66; pin core 2.65.0 2026-10-28 17:11:31 +00:00
docker-compose.yml config: set default INVITE_BASE_URL to i.deltachat.id 2026-08-22 00:55:18 +03:00
Dockerfile fix: add font packages to Dockerfile and configure font directories in resvg (v1.5.2) 2026-08-21 23:26:32 +03:00
favicon.ico v1.4.2: update avatar icon.jpg/icon.png and generate multi-resolution favicon.ico 2026-07-26 23:49:33 +03:00
formatting.py v1.18.0: keep the claim date as Linked, show contact sync changes as Updated 2026-10-29 18:15:17 +00:00
icon.jpg v1.4.2: update avatar icon.jpg/icon.png and generate multi-resolution favicon.ico 2026-07-26 23:49:33 +03:00
icon.png v1.4.2: update avatar icon.jpg/icon.png and generate multi-resolution favicon.ico 2026-07-26 23:49:33 +03:00
identicon.py v1.18.0: keep the claim date as Linked, show contact sync changes as Updated 2026-10-29 18:15:17 +00:00
LICENSE v1.13.0: /api/username lookup endpoint with invite link, MIT license 2026-10-16 13:26:10 +01:00
README.md v1.18.0: keep the claim date as Linked, show contact sync changes as Updated 2026-10-29 18:15:17 +00:00
requirements.txt v1.17.0: core 2.66.0, own address from the self contact 2026-10-28 20:02:21 +00:00
security.py fix: trust the right end of X-Forwarded-For, prune stale rate-limit entries, drop dead crawler-detection code 2026-09-20 22:26:22 +01:00
set_admin.py feat: initial release of Delta Chat Username Bot (v1.0.0) 2026-07-24 23:49:54 +03:00
transports_view.py Show the relay actually used for sending in /transports 2026-10-14 14:12:24 +01:00
update.sh v1.14.0: automatic account creation, releases by tag (#3) 2026-10-24 16:28:31 +01:00

🔗 Delta Chat Username & Short Link Bot (deltachat_username)

A Delta Chat bot and FastAPI web service for registering custom usernames and generating short invite links (https://deltachat.id/<username>) that redirect (via HTTP 307 Temporary Redirect) to standard Delta Chat invite URLs (https://i.delta.chat/#...).


✨ Features

  • 👤 Custom Usernames: Claim a short username (/username myname) for your personal profile or group chat.
  • 🔐 Visual Cryptographic Verification: Anti-impersonation verification displaying 10-group formatted PGP fingerprints, 5x5 symmetric Unicode block Identicons, and 5-emoji visual badges.
  • 🖼️ Social OpenGraph & Twitter Cards: Smart crawler detection serving rich metadata and cached dynamic PNG cards (1200x630) on Telegram, Discord, Twitter, WhatsApp, etc.
  • 📇 Web Profile Cards & Avatars: Dynamic endpoints (/{username}/og.png, /{username}/avatar.svg, and /{username}/card) for visual badges, QR codes, and web verification.
  • ⚡️ Group Chat Auto-Binding: Use /username myname directly inside any group chat — the bot instantly generates the group's invite URL without manual link pasting.
  • 🔀 HTTP 307 Temporary Redirect: Guarantees browsers and proxies always fetch the newest invite link without aggressive caching.
  • 🌐 Web Landing Page: Beautiful dark-mode glassmorphism interface on GET / displaying bot description, QR code, and interactive command hints.
  • 🔄 Contact Sync: A personal link follows its owner. When they write to the bot in the private chat where the link was registered, and once an hour for all personal links, the bot updates a= (address), r= (further relays, from the relay list in the contact's key) and n= (name). Relay changes reach the bot through the core's keyupdate messages (core 2.60+) even if the owner never writes. Only links with the contact's own key fingerprint are touched; fingerprint and invite tokens stay as they are, so a new key needs a new /link. Group, channel and ArcaneChat links are never rewritten. A sync does not change the claim date: cards show 📅 Linked (when /link was sent) and, once the link has changed since, 🔄 Updated.
  • 🛡️ Secure Administration: Authenticate ownership via /initadmin with cryptographic fingerprint verification.
  • 🔮 ArcaneChat Admin Groups: Invite links of ArcaneChat admin groups (z= parameter) are supported and shown as groups, marked ArcaneChat only in the chat card, /link reply, web page (no auto-redirect; the "Open in ArcaneChat" button is an openpgp4fpr: link that opens the installed app directly), social preview cards and the API ("arcanechat_only": true). They open only in ArcaneChat; Delta Chat would open a 1:1 chat with the inviter. The link is never rewritten when its owner writes to the bot.
  • 🤝 Lookup API for Bots (GET /api/username/<name>): returns {username, type, arcanechat_only, display_name, url, invite_link} as JSON, or 404 {"error": "not_found"}. url is the short link, invite_link the invite on i.delta.chat (the same link /username sends), which Delta Chat apps open directly without a browser. Bouncer Bot uses it to point people to a mentioned user who is not in the group. Shares the 10 requests/minute per IP limit with profile pages (429 {"error": "rate_limited"}).
  • 📡 Multi-Transport: Configure backup transports and see which relay the core sends through (/transports).

🚀 Quick Start & Deployment

1. Build Container

Clone repository and navigate to deltachat_username:

cd deltachat_username
cp .env.example .env
docker compose build

2. Configure Email and Admin (Optional)

Skip this step and the bot creates its account by itself at first start: the Delta Chat core (2.62+) picks the fastest chatmail relay from its built-in list and later adds further relays in the background.

To choose the account yourself, initialize it with your email and password, or with DCACCOUNT:server.tld for an account on a specific chatmail relay:

docker compose run --rm username_bot python bot.py init usernamebot@yourdomain.com "your_password"
docker compose run --rm username_bot python bot.py init DCACCOUNT:server.tld

Configure your admin email address and your cryptographic fingerprint on the server (or do it later inside the bot chat with the /initadmin command):

docker compose run --rm username_bot python set_admin.py --email admin@yourdomain.com
docker compose run --rm username_bot python set_admin.py --fingerprint 1234ABCD1234ABCD1234ABCD1234ABCD1234ABCD

3. Launch Bot Daemon

docker compose up -d

4. Claim Administrative Ownership

Send /initadmin to the bot in a private message in Delta Chat to complete admin identity verification.

5. Updates

Run ./update.sh (e.g. from cron) to deploy the newest release: the highest vX.Y.Z tag, from GitHub or, when GitHub is unreachable, from the Forgejo mirror; -f rebuilds the container without changes. Commits on main that are not released yet are not deployed. In .env.local, UPDATE_REF=v1.13.0 stays on that release (to roll back; remove it to follow new releases again), UPDATE_REF=main follows the branch, and MONITOR_URL pings a healthcheck on start, success and failure.

Releasing: merge, then git tag -a vX.Y.Z -m "..." <commit> && git push origin vX.Y.Z. Pushing the tag publishes the GitHub release with that version's CHANGELOG.md section (the tag must match VERSION in commands.py), then sends the ntfy notification and the Home Assistant add-on sync.


🤖 Bot Commands

Command Scope Description
/username All Check your current chat's registered username and short link.
/username <name> All Look up short link for any registered username.
/link <name> <url> Private Bind custom username & invite link (replaces old username if present).
/link <name> Group Auto-generate group invite link and bind username.
/unlink All Unlink registered username from current chat.
/unlink <name> Admin Force-unlink a registered username.
/help All Show command help and bot info.
/donate All Support bot development.
/initadmin Admin Claim administrative ownership.
/url <url> Admin Set base domain URL (https://deltachat.id).
/inviteurl <url> Admin Set custom invite base URL/mirror (https://i.gluek.info/#).
/stats Admin Show registered usernames and database stats.
/transports Admin Show mail relays: relay used for sending, send queue, incoming status and storage.
/addtransport <uri/creds> Admin (Private) Add a backup mail transport relay.
/rmtransport <addr> Admin Remove a configured mail transport.

Relay selection and failover are handled by the Delta Chat core (2.61+): it keeps sending through the relay that last worked and moves to the next one only if it cannot connect, so the relay used for sending can differ from the account's main address. /transports shows which relay that is, the core's send queue, and per relay the incoming status, the last received message and mailbox storage. The former /setprimary and /resilient commands are deprecated and only reply with this explanation.


Target-Specific Commands in Group Chats

In group chats where multiple bots are present, you can address this bot specifically to prevent other bots from responding. Append the @username (or @user, @usernamebot) suffix to any command, for example:

  • /help@username
  • /stats@username

A plain /help sent in a group chat is answered in a private 1:1 chat with the sender, so several bots don't flood the group with help texts. Use /help@username to show the help in the group itself.

🌐 Caddy Configuration

Add to your /etc/caddy/Caddyfile:

deltachat.id, d.gluek.info {
    reverse_proxy 127.0.0.1:8080
}

www.deltachat.id {
    redir https://deltachat.id{uri} permanent
}

🧪 Running Unit Tests

python3 -m unittest discover -s tests -p "test_*.py" -v

❤️ Support & Development

If you find this bot useful, consider supporting its development:

License

MIT, see LICENSE.