/add-deltachat

name: add-deltachat
description: Add DeltaChat channel integration via @deltachat/stdio-rpc-server. Native adapter — no Chat SDK bridge. Email-based messaging with end-to-end encryption.

Add DeltaChat Channel

The adapter drives the `@deltachat/stdio-rpc-server` JSON-RPC subprocess directly — pure Node.js against the DeltaChat core library. Messages are delivered over email with Autocrypt/OpenPGP encryption.

Install

1. Copy the adapter and its registration test

Fetch the `channels` branch from the configured remote that carries it, then overwrite the skill-owned files with the canonical registry copies:

src/channels/deltachat.ts
src/channels/deltachat-registration.test.ts

2. Append the self-registration import

Append to `src/channels/index.ts` (skip if already present):

import './deltachat.js';

3. Install the adapter package (pinned)

@deltachat/stdio-rpc-server@2.49.0

4. Build and validate

pnpm run build

pnpm exec vitest run src/channels/deltachat-registration.test.ts

Both must be clean before proceeding. `deltachat-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `deltachat`. It goes red if the `import './deltachat.js';` line is deleted or drifts, if the barrel fails to evaluate (so the channel genuinely would not register), or if `@deltachat/stdio-rpc-server` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. Importing is safe: deltachat instantiates the rpc client only in `setup()` (at host startup), never at import.

End-to-end message delivery against a real email account is verified manually once the service is running — see Wiring and Troubleshooting.

Account Setup

A dedicated email account is strongly recommended — it will accumulate DeltaChat-formatted messages and store encryption keys. Not all providers work well with DeltaChat; check https://providers.delta.chat/ before picking one.

**Default security modes:** IMAP uses SSL/TLS (port 993), SMTP uses STARTTLS (port 587). Both are configurable via `.env` — see Credentials below.

To find the correct hostnames for a domain:

node -e "require('dns').resolveMx('example.com', (e,r) => console.log(r))"

Most providers publish their IMAP/SMTP hostnames in their help docs under "manual setup" or "IMAP access."

Credentials

Add to `.env`:

DC_EMAIL=bot@example.com
DC_PASSWORD=your-app-password
DC_IMAP_HOST=imap.example.com
DC_IMAP_PORT=993
DC_IMAP_SECURITY=1        # 1=SSL/TLS (default), 2=STARTTLS, 3=plain
DC_SMTP_HOST=smtp.example.com
DC_SMTP_PORT=587
DC_SMTP_SECURITY=2        # 2=STARTTLS (default), 1=SSL/TLS, 3=plain

Security settings are applied on every startup, so changing them in `.env` and restarting takes effect without wiping the account.

Optional settings

The following are read from the process environment (not `.env`). To override them, add `Environment=` lines to the systemd service unit or your launchd plist:

| Variable | Default | Description | |----------|---------|-------------| | `DC_ACCOUNT_DIR` | `dc-account` | Directory for DeltaChat account data (IMAP state, keys, blobs) | | `DC_DISPLAY_NAME` | `NanoClaw` | Bot display name shown in DeltaChat | | `DC_AVATAR_PATH` | _(none)_ | Absolute path to avatar image; set at startup only |

The `/set-avatar` command (send an image with that caption) is the easiest way to set the avatar at runtime without modifying the service file. Only users with `owner` or global `admin` role can use it.

Restart

Run from your NanoClaw project root:

source setup/lib/install-slug.sh

# Linux
systemctl --user restart $(systemd_unit)

# macOS
launchctl kickstart -k gui/$(id -u)/$(launchd_label)

On first start the adapter configures the email account (IMAP/SMTP credentials, calls `configure()`). Subsequent starts skip straight to `startIo()`. Account data is stored in `dc-account/` in the project root (or your `DC_ACCOUNT_DIR`).

Wiring

DMs

**DeltaChat contacts cannot be added by email alone** — to start a chat, the user must open the bot's invite link in their DeltaChat app or scan its QR code. This triggers the SecureJoin handshake.

Step 1 — Get the invite link

After the service starts, the adapter logs the invite URL and writes a QR SVG:

grep "invite link" logs/nanoclaw.log | tail -1
# url field contains the https://i.delta.chat/... invite link
# also written to dc-account/invite-qr.svg (or $DC_ACCOUNT_DIR/invite-qr.svg)

The invite URL is stable (tied to the bot's email and encryption keys) so it stays valid across restarts.

Step 2 — Add the bot in DeltaChat

Two options for the user to connect:

• **Link**: Copy the `https://i.delta.chat/...` URL and open it on the device running DeltaChat. The app recognises it and shows a "Start chat" prompt.
• **QR code**: Open `dc-account/invite-qr.svg` in a browser or image viewer, display it on screen, and scan it from the DeltaChat app using the QR-scan button on the new-chat screen.

After accepting, DeltaChat exchanges keys and creates the chat automatically.

Step 3 — Wire the chat to an agent

Once the first message arrives the router auto-creates a `messaging_groups` row. Look up the chat ID:

pnpm exec tsx scripts/q.ts data/v2.db \
  "SELECT platform_id, name FROM messaging_groups WHERE channel_type='deltachat' AND is_group=0 ORDER BY created_at DESC LIMIT 5"

Then run `/init-first-agent` — it creates the agent group, grants the user owner access, and wires the messaging group in one step:

pnpm exec tsx scripts/init-first-agent.ts \
  --channel deltachat \
  --user-id deltachat:user@example.com \
  --platform-id <platform_id from above> \
  --display-name "Your Name"

Groups

Add the bot email to a DeltaChat group.