Currently URI schemes are mainly supported by the app-internal QRcode scanner, at this time only openpgp4fpr (used for securejoin) is also registered as uri scheme handler on all platforms (android, ios and desktop)
- related forum topic: https://support.delta.chat/t/custom-deltachat-url-uri-scheme/346
- core sourcecode that handles uri schemes: https://github.com/deltachat/deltachat-core-rust/blob/master/src/qr.rs and https://github.com/deltachat/deltachat-core-rust/blob/master/src/securejoin/qrinvite.rs
Generic deltachat scheme, currently used by android as callback url for the oauth2 login method.
| Scheme | chat.delta |
| Used for | oauth2 Login (only android currently) |
| Related Terms* | - |
| Available on | iOS (defined, but not used yet), android |
| Handled by the core | No |
| Other apps using it | none, only DeltaChat |
| Notes | Only used as scheme currently, not in qr codes |
[TODO]
<!-- this scheme is used as the redirect_url for getOauth2Url()
and should be whitelisted by the supported oauth2 services -->
<data android:scheme="chat.delta" android:path="/${applicationId}/auth" tools:ignore="AppLinkUrlError"/>
<data android:scheme="chat.delta" android:path="/auth" tools:ignore="AppLinkUrlError"/>| Scheme | OPENPGP4FPR: |
| Used for | Verify Contact and Join a group |
| Related Terms* | Securejoin |
| Available on | iOS, android, desktop |
| Decoded by the core** | Yes |
| Other apps using it |
OPENPGP4FPR:FINGERPRINT#a=ADDR&n=NAME&i=INVITENUMBER&s=AUTH
OPENPGP4FPR:FINGERPRINT#a=ADDR&g=GROUPNAME&x=GROUPID&i=INVITENUMBER&s=AUTH
The fields a, g and n are URL encoded.
i & s are 66 random bits endcoded as base-64.
Note: Everything after
#is a Delta Chat extensionThe
OPENPGP4FPRscheme's data is also used for so called "Invite Links"
verify contact
OPENPGP4FPR:EEA98F87742EF2FD6C23677F1E1142828C202998#a=demo.fn8hk%40five.chat&n=&i=rd82URz8_ac&s=MFRLUHvIHlq
join regular group
OPENPGP4FPR:EEA98F87742EF2FD6C23677F1E1142828C202998#a=demo.fn8hk%40five.chat&g=groupname2&x=iNekF7uW509&i=xW0ZAcLUQDf&s=OYV-PWe63Vv
join verified/protected group (same format as join regular group)
OPENPGP4FPR:EEA98F87742EF2FD6C23677F1E1142828C202998#a=demo.fn8hk%40five.chat&g=groupname&x=ylTH55NJF24&i=PpDNY9sRkh-&s=F8di8fNDToQ
Invite Links: https://i.delta.chat
| Universal link | https://i.delta.chat |
| Used for | Verify Contact and Join a group |
| Related Terms* | Securejoin, universal links |
| Available on | iOS, android, desktop (only QR and paste) |
| Decoded by the core** | Yes |
| Other apps using it | No, not possible without a pr to the invite repo |
"Invite Links" are an alternative to scan each other's QR code to get in contact or to join groups.
The existing OPENPGP4FPR links have 2 major problems: they are not usable by people who don't have Delta Chat installed and they are not linkified (and thus not shareable) on 3rd party platforms.
The "Invite Links" solve these problems:
- You can share them over any 3rd party platform.
- If recipients taps the links, they are either offered to install Delta Chat and tap an "Open Chat" link or, depending on the platform, an installed Delta Chat opens directly without even going to the website.
Since the 1.44 releases the qr codes that you copy to clipboard have this format.
https://i.delta.chat/#FINGERPRINT&a=ADDR&n=NAME&i=INVITENUMBER&s=AUTH
https://i.delta.chat/#FINGERPRINT&a=ADDR&g=GROUPNAME&x=GROUPID&i=INVITENUMBER&s=AUTH
The syntax is the same as in OPENPGP4FPR with two differences:
OPENPGP4FPR:is replaced byhttps://i.delta.chat/#- The
#that comes directly after theFINGERPRINTis replaced by an&character.- This is to make browsers and operating systems handle the link correctly
Note, that all data are added to the URI Fragment, by that, no user data is sent to the server.
get in contact / verify contact
https://i.delta.chat/#EEA98F87742EF2FD6C23677F1E1142828C202998&a=demo.fn8hk%40five.chat&n=&i=rd82URz8_ac&s=MFRLUHvIHlq
join regular group
https://i.delta.chat/#EEA98F87742EF2FD6C23677F1E1142828C202998&a=demo.fn8hk%40five.chat&g=groupname2&x=iNekF7uW509&i=xW0ZAcLUQDf&s=OYV-PWe63Vv
join verified/protected group (same format as join regular group)
https://i.delta.chat/#EEA98F87742EF2FD6C23677F1E1142828C202998&a=demo.fn8hk%40five.chat&g=groupname&x=ylTH55NJF24&i=PpDNY9sRkh-&s=F8di8fNDToQ
- Sourcecode of the website
https://i.delta.chat: https://github.com/deltachat/invite/ - The file that tell apple which apps are allowed to handle this universal link: https://github.com/deltachat/invite/blob/main/.well-known/apple-app-site-association
- Deeplinking on the different platforms
- Apple Universal Links: https://developer.apple.com/ios/universal-links/
- Android App Links: https://developer.android.com/training/app-links/
| Scheme | DCACCOUNT: |
| Used for | Account setup |
| Related Terms* | Burner Accounts |
| Available on | iOS (only QR), android(only QR), desktop (only QR) |
| Decoded by the core ** | Yes |
| Other apps using it | none, only DeltaChat |
currently this only accepts a url that gives back account setup information as a json object. see the mailadm project for more details as this api was designed for use with burner account qr codes generated by mailadm.
DCACCOUNT:https://example.org/new_email?t=1w_7wDjgjelxeX884x96v3
You may want to use DCLOGIN instead, if you want a qr code containing login information for a single account.
HTTP Status code 200
{
email: string,
password: string
}json object can have other properties too, but currently they are ignored by core.
HTTP Status code: NOT 2XX, idealy the 4XX if it's user error and 5XX if it's the servers fault
{
// The user facing error string, should explain what failed.
error: string,
}json object can have other properties too, but currently they are ignored by core.
| Scheme | DCLOGIN: |
| Used for | Account setup |
| Related Terms* | Account Login QR code |
| Available on | draft |
| Decoded by the core ** | draft |
| Other apps using it | none, only DeltaChat |
The generic URI schema is:
URI = scheme ":" ["//" authority] path ["?" query] ["#" fragment] authority = [userinfo "@"] host [":" port]
For DCLOGIN this means:
- scheme is always dclogin
- There must be an authority section
- The userinfo part is required.
- The path may be omitted or be a single
/. - The fragment must be omitted.
- The query parameters are described down below.
Examples:
dclogin://user@host/?p=password&v=1[&options]
# example: (email: [email protected], password: securePassword)
dclogin://[email protected]?p=securePassword&v=1
# example: (email: [email protected], password: url/Encoded\@passw@rd)
dclogin://[email protected]?p=url%2FEncoded%5C%40passw%40rd&v=1
# example: (email: [email protected], password: 123456, insecure smtp at different server)
dclogin://[email protected]?p=123456&v=1&sh=mail.example.com&sc=3&ss=plain
Format: URL Query parameters also known as GET variables (varname=value behind the question mark, chained/delimited by &)
The query parameters contain advanced options and a version parameter.
All advanced options are optional except for v and p, which are the only required options at this point.
(BTW: Later/Other versions in the future might specify a different authentication and thus p might become unnecessary in those formats.)
| short name | stands for | description | example |
|---|---|---|---|
v |
version |
defines the format version, more explanation below | v=1 |
p |
password |
required in version 1, password of the account | |
| ---------- | ------------------------- | --------------------------------------------------- | ---------------- |
ih |
imap_host |
IMAP host | ih=imap.example.com |
ip |
imap_port |
IMAP port | ip=993 |
iu |
imap_username |
IMAP username | |
ipw |
imap_password |
IMAP password | |
is |
imap_security |
IMAP security: "ssl" or "default" or "plain" |
is=ssl |
ic |
imap_certificate_checks |
IMAP certificate checks, see below for options | ic=1 |
| ---------- | ------------------------- | --------------------------------------------------- | ---------------- |
sh |
smtp_host |
SMTP host | sh=mail.example.com |
sp |
smtp_port |
SMTP port | sp=465 |
su |
smtp_username |
SMTP username | |
spw |
smtp_password |
SMTP password | |
ss |
smtp_security |
SMTP security: "ssl", "starttls" or "plain" |
ss=plain |
sc |
smtp_certificate_checks |
SMTP certificate checks, see below for options | sc=3 |
Format version: Used for breaking new versions that add new required properties, basically deltachat checks for this and if it's newer than the version deltachat supports it prompts the user to update the app.
The version number only increases on incompatible changes (changes to required properties).
New versions of Delta Chat do not have separate options for IMAP certificate checks and SMTP certificate checks.
For best compatibility both ic and sc must be always set to the same value.
sc is actually ignored by new Delta Chat and ic is used to configure both IMAP and SMTP certificate checks.
| code | name & description |
|---|---|
| 0 | Automatic, same as AcceptInvalidCertificates unless overridden by strict_tls setting in provider database. |
| 1 | Strict |
| 3 | AcceptInvalidCertificates |
- There is a maximum length of how much data fits in side of a qr code (depending on the error correction level 1273 chars to 2953 chars)
- only use the short names for advanced properties
- If working with long domains/password/usernames in advanced options, consider creating a configuration file at the server instead using either Autoconfigure
- Every value (username & password too) needs to be URI encoded:
implementations should be somewhat tolerant:
- both
dclogin:anddclogin://should work (though onlydclogin://is technically correct) - only implement short names (not the full names they stand for)
- have a test for usename+extension@host cases
- if version number is higher than what is implemented, tell the user to update
| Scheme | DCWEBRTC: |
| Used for | Setting the WebrtcInstance config value from an qrcode |
| Related Terms* | webrtc_instance |
| Available on | ? [TODO] |
| Decoded by the core ** | Yes |
| Other apps using it | none, only DeltaChat |
DCWEBRTC:[address of video call service]
Here is a list of variables that can be used in the config value, these might not be updated in the future, so you should also check to current documentation if it doesn't work.
$ROOMgets replaced with a random string.$NOROOMgets replcaed with an empty string- if no variable is set a random string is appended to the url
jitsi
DCWEBRTC:https://meet.jit.si/$ROOM
service with no random roomname, webex in this case
DCWEBRTC:https://choosenname.my.webex.com/meet/me/$NOROOM
| Scheme | DCBACKUP: |
| Used for | transferring a backup to another deltachat device |
| Related Terms* | - |
| Available on | android, ios, desktop |
| Decoded by the core | Yes |
| Other apps using it | No |
DCBACKUP:data
The data itself contains an encoded iroh::provider::Ticket
structure serialised using it's Display trait. Ultimately that
implementation is the reference but here the details:
- The ticket itself consists of this struct:
struct Ticket { hash: [u8; 32], peer: [u8; 32], addrs: Vec<SocketAddr>, token: [u8; 32], } - This ticket is serialised to bytes using postcard.
- These bytes are encoded using Base64 URL SAFE without padding.
This shows what a ticket looks like in practice.
DCBACKUP:IA84ohZpKlLVQaIe0AEejanGo2CCKmAgMQJLIcmO4Kp5IFNwcau_-xuQ2AhMSVWmodA63wUY7YmhSDVQh6tuCE8WAQB_AAAB0SJh2W8_TB3azsiP88tJXNEi554F4M7Q_jTw2_EnMdvrvQ
Usable as share to deltachat.
| Scheme | mailto: |
| Used for | sharing to deltachat, creating a contact |
| Related Terms* | - |
| Available on | android, desktop (own decoding), [TODO does ios support it?] |
| Decoded by the core | Yes, partially (only extracts address and creates contact) |
| Other apps using it | most other email clients |
mailto:[addr]?subject=[subject]&body=[body]
standard mailto syntax though deltachat might not respect all options yet, probably refer to https://tools.ietf.org/html/rfc2368 and https://tools.ietf.org/html/rfc6068.
similar to mailto:
| Scheme | SMTP: |
| Used for | sharing to deltachat, creating a contact |
| Related Terms* | - |
| Available on | ? [TODO] |
| Decoded by the core | Yes, partially (only extracts address and creates contact) |
| Other apps using it | ? |
SMTP:[addr]:[subject]:[body]
similar to mailto:
| Scheme | MATMSG: |
| Used for | sharing to deltachat, creating a contact |
| Related Terms* | - |
| Available on | ? [TODO] |
| Decoded by the core | Yes, partially (only extracts address and creates contact) |
| Other apps using it | ? |
MATMSG:TO:[addr];SUB:[subject];BODY:[body];
| Scheme | BEGIN:VCARD |
| Used for | importing a contact |
| Related Terms* | vcard |
| Available on | ? [TODO] |
| Decoded by the core | Yes |
| Other apps using it | ? |
VCARD:BEGIN\nN:last name;first name;...;\nEMAIL;<type>:addr...;
http://&https://- to make the qr code scanner more complete and allow users to scan common qr codes.
List of which schemes the app is registered to handle in the OS. When an scheme is reqistered as a handler
| Platform | Schemes | Sources (and a keyword to look for when the line-numbers have changed) |
|---|---|---|
| iOS | mailto:***, chat.delta, openpgp4fpr:, dclogin:, dcaccount:, https://i.delta.chat |
deltachat-ios/Info.plist CFBundleURLSchemes |
| android | mailto:, chat.delta, openpgp4fpr:, dclogin:, dcaccount:, https://i.delta.chat |
AndroidManifest.xml search for android:scheme |
| desktop | mailto:***, openpgp4fpr:, dclogin:, dcaccount: |
build/gen-electron-builder-config.js build['protocols'] src/main/windows/main.ts#L61 app.on('open-url', ...) |
Caveat: the flathub version has sometimes problems in the support of uri schemes see: flathub/chat.delta.desktop#115
* terms that are used in the project that are related to it. Sometimes there are multiple terms refering to the same thing, for example contact requests are still sometimes refered to as "dead drops".
** wether the core has logic to detect and decode it
*** not usable yet, does not work out of the box on desktop and for iOS we need to request permission from apple