BOT TUTORIAL

Get the issue bot to reply.

1. Start and verify it

release_unpack=$(mktemp -d /tmp/lettres-0.20.0.XXXXXX)
tar -xzf lettres-0.20.0.tar.gz -C "$release_unpack"
cd "$release_unpack/lettres"
doas ./install.sh --issue-bot
export PATH="$HOME/.local/bin:$PATH"
lettres bot status

Use a newly created empty extraction directory for every release. Success reports lettres-issues, state ready, a recent authenticated poll, the public key fingerprint, and the workflow-access mode. Reinstalling preserves the bot identity, contacts, reports, flow state, evidence, and reply queue.

2. Export the public contact

lettres issues contact ./lettres-issue-tracker.contact.json

Alternatively, open the protected relay /admin page, find Lettres Issue Tracker under Authorized identities, select Public contact, then Download. Share only this signed .contact.json. Never share the bot's private .identity.json.

3. Connect a user

  1. In Lettres select + Add contact.
  2. Choose the bot .contact.json, compare its fingerprint, and select Trust this key.
  3. Open Lettres Issue Tracker · BOT and send /help.
  4. Send a direct problem description. The expected reply starts Created issue #… and includes first-use guidance.

The bot validates and persists the sender's signed public introduction automatically; users never give it a private identity and do not need a second manual contact import.

4. Use it

/report DESCRIPTION
/report
/issues
/show 42
/edit 42
/delete 42
/cancel
/help

Greetings, /start, and /help explain the workflow without creating a report. A first direct description is recorded once. Reporters manage their own issues; configured maintainers may use /issues all. The server-operated bot decrypts reports for the operator/maintainers.

5. Verify or diagnose

lettres bot status
lettres bot logs --tail 100
lettres bot logs --follow
lettres issues list

Status distinguishes disabled, stopped, reconnecting, stale, and ready states. lastReplyAccepted shows the most recent relay-accepted reply; seeing the decrypted reply in the user's conversation is the end-to-end proof. Logs identify incoming message, contact import, policy, issue mutation, durable reply, relay acceptance, and retry stages without report contents or credentials.

Optional bot-only access

lettres bot access allowlist ltr_FIRST_KEY,ltr_SECOND_KEY
lettres bot password
lettres bot access relay

The default is all relay-approved users. Password users send /access PASSWORD; only a salted verifier is stored, attempts are bounded, and authorization messages never become reports. This password is unrelated to relay enrollment and /admin.

No reply?

  1. Run lettres bot status.
  2. Compare its bot key with the imported contact and lettres users list.
  3. Follow logs and look, in order, for incoming_operation, sender_contact_imported, workflow_authorization, reply_intent_recorded, and reply_relay_accepted.
  4. Correct the named network, contact, policy, storage, or reply stage. Do not regenerate the identity or clear the issue database/cursor.

Build the included echo bot

lettres identity generate "Echo bot" /opt/lettres-bots/echo/identity 730 bot
lettres users add /opt/lettres-bots/echo/identity/echo-bot.contact.json bot
docker build -f examples/bots/Dockerfile -t lettres-echo-bot:0.20.0 .

Mount the private identity read-only, and mount both its state and contacts directories writable by the bot UID. The SDK verifies the first signed sender introduction, stores only its canonical public contact, filters protocol controls/own echoes, and lets the handler call bot.sendText(sender, ...). Full runnable Docker arguments, persistence layout, security boundaries, and SDK code are in docs/bot-guide.md.