PicoClaw

Back to README

Delta Chat Channel

PicoClaw can run as a Delta Chat bot.

DeltaChat is a distributed chatmail messaging system built on top of a jsonrpc server that manages all the encryption, storage, proxy and account management.

You can read more about the project in https://delta.chat

Install

Download or install the Delta Chat RPC server from the GitHub releases or Pip:

pip install deltachat-rpc-server
which deltachat-rpc-server

Prebuilt binaries are also available from the Delta Chat core releases

The JSONRPC protocol is somehow stable and the picoclaw implementation will always try to keep up with latest releases of deltachat core. The deltachat channel for PicoClaw is known to work with chatmail core v2.53.

Configure

The easiest setup is to let PicoClaw create a chatmail account in Delta Chat’s local account store. Put a relay marker in email using an empty user part, for example @nine.testrun.org:

{
  "channel_list": {
    "deltachat": {
      "enabled": true,
      "type": "deltachat",
      "allow_from": ["friend@example.org"],
      "group_trigger": {
        "mention_only": true
      },
      "settings": {
        "email": "@nine.testrun.org",
        "display_name": "PicoClaw Bot",
        "avatar_image": "/home/me/bot-avatar.png",
        "show_invite_link": true
      }
    }
  }
}

On startup, PicoClaw creates the account through deltachat-rpc-server, then stops with an error that contains the generated address. Replace the relay marker with that full email address and run PicoClaw again:

{
  "email": "bot123@nine.testrun.org",
  "display_name": "PicoClaw Bot",
  "avatar_image": "/home/me/bot-avatar.png"
}

If email is missing, the startup error points at the default chatmail relay (nine.testrun.org) and the official relay directory at https://chatmail.at/relays.

display_name and avatar_image are optional profile settings. When present, PicoClaw applies them on every startup, so changing the avatar path in config is enough to update the bot profile.

Field	Required	Description
email	Yes	Full bot mailbox address, or first-run relay marker such as @nine.testrun.org
rpc_server_path	No	Path to deltachat-rpc-server; only needed when it is not on PATH
display_name	No	Startup-applied profile name shown to contacts and used for group mention detection
avatar_image	No	Startup-applied profile avatar image path; ~ is expanded. Missing files are warned and ignored
data_dir	No	Account database directory. Default: ~/.picoclaw/deltachat/<channel-name>
join_invite_link	No	Delta Chat invite link for the bot account to join on startup
show_invite_link	No	When true, prints the bot account’s own invite link and QR code on startup so peers can add it. Omitted or false suppresses the startup printout
allow_crosspost	No	Default false. When true, senders allowed by allow_from may use message tool targets outside the current chat, or resolve recipients by email/contact/chat name

Standard channel fields such as allow_from, group_trigger, and reasoning_channel_id also apply.

First Run

Running picoclaw setup reset will generate a blank ~/.picoclaw/config.json file with the default values.

With email set to @server (without the username defined), PicoClaw creates the chatmail account, and stops with an startup error displaying the autogenerated full email that needs to be replaced manually in the configuration file.

Starting up the gateway again will use show_invite_link to display the invite link and QR code to let your user to comunicate with it.

Omit the field or set it to false to suppress the startup printout.

Behavior

• Direct chats always respond after allow_from passes.
• Group chats follow group_trigger; without one, every group message is handled.
• Messages from the bot itself, device chats, and info/system messages are ignored.
• Accepted inbound messages are marked seen after successful dispatch to the agent, with Delta Chat read receipts enabled so peer clients can show the double-check seen state; dispatch failures leave the message unseen.
• Accepted contact-request chats are accepted before the seen mark, because Delta Chat does not send read receipts while a chat is still a contact request.
• Incoming attachments (images, audio, video, documents) are registered with the media store and handed to the agent, so it can view images or operate on the files directly. If no media store is available, the path is appended inline as [attachment: /path] instead.
• Outbound attachments are supported: when the agent emits media, each file is sent as a Delta Chat message (with the caption as text). Delta Chat infers the view type from the file, so images, GIFs, and videos render natively.
• Crosspost recipient lookup is disabled by default. The agent can always reply to the current numeric chat ID, but sending to another numeric chat ID or resolving an email/contact/chat name requires allow_crosspost: true and the current sender must pass allow_from; allow_from: ["*"] allows this for any sender.
• Voice is supported in both directions when voice providers are configured: incoming voice notes are transcribed by the agent’s ASR and the transcript is passed to the model; the agent can reply with synthesized speech, which is delivered as a native Delta Chat voice message (send_tts). This requires an ASR and/or TTS provider under voice — it is not Delta Chat-specific config.

Troubleshooting

Symptom	Fix
deltachat-rpc-server not found on PATH or rpc_server_path ... not found	Install the RPC server on PATH, or set rpc_server_path to an absolute path
email is required	Set email to a first-run marker such as @nine.testrun.org, run picoclaw g, then replace it with the generated full email. Other chatmail relays are listed at https://chatmail.at/relays
created chatmail account ...	Replace the @server marker in email with the generated full email and run PicoClaw again
account ... is not configured in data_dir	Point data_dir at the existing JSON-RPC account store, or use email="@server" to create one
Bot does not answer in a group	Check group_trigger; mention display_name or use a configured prefix
Bot ignores a sender	Add the sender email to allow_from, or use ["*"] for open access
Sender cannot message the bot	Re-add the bot with the startup QR/invite so Delta Chat can establish encryption
Agent cannot send to an email/name/other chat ID	Enable settings.allow_crosspost and allow the controlling sender in allow_from; this capability is disabled by default for privacy

Transition From Legacy Options

The Delta Chat channel does not keep backward-compatible aliases for the old configuration options. Update existing configs before starting the new binary: unknown legacy keys are ignored by the current settings decoder, so leaving them in place can make the channel start with missing behavior instead of migrating automatically.

Use this mapping when updating channel_list.<name>.settings:

Old option	New option or action
invite_link	Rename to join_invite_link
Always printing the bot invite	Add show_invite_link: true when you want the startup invite link and QR code
password	Remove. PicoClaw no longer configures mailbox passwords; the selected account must already be configured in the Delta Chat JSON-RPC account store, or be created through the @relay chatmail bootstrap flow
imap_server, imap_port	Remove. Manual IMAP setup is no longer handled by PicoClaw
smtp_server, smtp_port	Remove. Manual SMTP setup is no longer handled by PicoClaw
PICOCLAW_CHANNELS_DELTACHAT_INVITE_LINK	Rename to PICOCLAW_CHANNELS_DELTACHAT_JOIN_INVITE_LINK
PICOCLAW_CHANNELS_DELTACHAT_PASSWORD	Remove

For an existing configured account, keep the account database and point the new config at it:

{
  "channel_list": {
    "deltachat": {
      "enabled": true,
      "type": "deltachat",
      "allow_from": ["friend@example.org"],
      "group_trigger": {
        "mention_only": true
      },
      "settings": {
        "email": "bot@example.org",
        "data_dir": "~/.picoclaw/deltachat/deltachat",
        "join_invite_link": "DCJOIN:...",
        "show_invite_link": true,
        "allow_crosspost": false
      }
    }
  }
}

If the old setup depended on password plus IMAP/SMTP fields to configure a classic mailbox, use this plan:

1. Configure that mailbox in a Delta Chat JSON-RPC account store outside PicoClaw, or switch to a chatmail account by setting email to a relay marker such as @nine.testrun.org.
2. Remove the legacy password and server fields from config.json, ~/.picoclaw/.security.yml, and the environment, then set email and data_dir to the configured account.
3. Start PicoClaw. If it reports account ... is not configured in data_dir, the email does not match an account in that data_dir; fix one of those values or use the @relay bootstrap flow to create a new chatmail account.

This site is open source. Improve this page.