API Reference

Delta Chat JSON-RPC high-level API.

class deltachat_rpc_client.Account(manager: DeltaChat, id: int)[source]

Delta Chat account.

bring_online()[source]

Start I/O and wait until IMAP becomes IDLE.

check_qr(qr)[source]

Parse QR code contents.

This function takes the raw text scanned and checks what can be done with it.

clear_all_events()[source]

Remove all queued-up events for a given account.

Useful for tests.

clone() Account[source]

Clone given account.

This uses backup-transfer via iroh, i.e. the ‘Add second device’ feature.

create_chat(account: Account) Chat[source]

Create a 1:1 chat with another account.

create_contact(obj: int | str | Contact | Account, name: str | None = None) Contact[source]

Create a new Contact or return an existing one.

Calling this method will always result in the same underlying contact id. If there already is a Contact with that e-mail address, it is unblocked and its display name is updated if specified.

Parameters:
  • obj – email-address, contact id or account.

  • name – (optional) display name for this contact.

create_group(name: str, protect: bool = False) Chat[source]

Create a new group chat.

After creation, the group has only self-contact as member and is in unpromoted state.

delete_messages(messages: list[Message]) None[source]

Delete messages (local and remote).

property device_contact: Chat

Account’s device contact.

export_backup(path, passphrase: str = '') None[source]

Export backup.

export_self_keys(path) None[source]

Export keys.

get_avatar() str | None[source]

Get self avatar.

get_blocked_contacts() list[AttrDict][source]

Return a list with snapshots of all blocked contacts.

get_chat_by_contact(contact: int | Contact) Chat | None[source]

Return 1:1 chat for a contact if it exists.

get_chat_by_id(chat_id: int) Chat[source]

Return the Chat instance with the given ID.

get_chatlist(query: str | None = None, contact: Contact | None = None, archived_only: bool = False, for_forwarding: bool = False, no_specials: bool = False, alldone_hint: bool = False, snapshot: bool = False) list[Chat] | list[AttrDict][source]

Return list of chats.

Parameters:
  • query – if a string is specified only chats matching this query are returned.

  • contact – if a contact is specified only chats including this contact are returned.

  • archived_only – if True only archived chats are returned.

  • for_forwarding – if True the chat list is sorted with “Saved messages” at the top and without “Device chat” and contact requests.

  • no_specials – if True archive link is not added to the list.

  • alldone_hint – if True the “all done hint” special chat will be added to the list as needed.

  • snapshot – If True return a list of chat snapshots instead of Chat instances.

get_config(key: str) str | None[source]

Get configuration value.

get_contact_by_addr(address: str) Contact | None[source]

Check if an e-mail address belongs to a known and unblocked contact.

get_contact_by_id(contact_id: int) Contact[source]

Return Contact instance for the given contact ID.

get_contacts(query: str | None = None, *, with_self: bool = False, snapshot: bool = False) list[Contact] | list[AttrDict][source]

Get a filtered list of contacts.

Parameters:
  • query – if a string is specified, only return contacts whose name or e-mail matches query.

  • with_self – if True the self-contact is also included if it matches the query.

  • snapshot – If True return a list of contact snapshots instead of Contact instances.

get_device_chat() Chat[source]

Return device chat.

get_fresh_messages() list[Message][source]

Return the list of fresh messages, newest messages first.

This call is intended for displaying notifications. If you are writing a bot, use get_fresh_messages_in_arrival_order() instead, to process oldest messages first.

get_fresh_messages_in_arrival_order() list[Message][source]

Return fresh messages list sorted in the order of their arrival, with ascending IDs.

get_info() AttrDict[source]

Return dictionary of this account configuration parameters.

get_message_by_id(msg_id: int) Message[source]

Return the Message instance with the given ID.

get_next_messages() list[Message][source]

Return a list of next messages.

get_qr_code() str[source]

Get Setup-Contact QR Code text.

This data needs to be transferred to another Delta Chat account in a second channel, typically used by mobiles with QRcode-show + scan UX.

get_qr_code_svg() tuple[str, str][source]

Get Setup-Contact QR code text and SVG.

get_size() int[source]

Get the combined filesize of an account in bytes.

import_backup(path, passphrase: str = '') None[source]

Import backup.

import_self_keys(path) None[source]

Import keys.

import_vcard(vcard: str) list[Contact][source]

Import vCard.

Return created or modified contacts in the order they appear in vCard.

initiate_autocrypt_key_transfer() None[source]

Send Autocrypt Setup Message.

is_configured() bool[source]

Return True if this account is configured.

make_vcard(contacts: list[Contact]) str[source]

Create vCard with the given contacts.

mark_seen_messages(messages: list[Message]) None[source]

Mark the given set of messages as seen.

remove() None[source]

Remove the account.

secure_join(qrdata: str) Chat[source]

Continue a Setup-Contact or Verified-Group-Invite protocol started on another device.

The function returns immediately and the handshake runs in background, sending and receiving several messages. Subsequent calls of secure_join() will abort previous, unfinished handshakes. See https://securejoin.delta.chat/ for protocol details.

Parameters:

qrdata – The text of the scanned QR code.

property self_contact: Contact

Account’s identity as a Contact.

set_avatar(img_path: str | None = None) None[source]

Set self avatar.

Passing None will discard the currently set avatar.

set_config(key: str, value: str | None = None) None[source]

Set configuration value.

set_config_from_qr(qr: str)[source]

Set configuration values from a QR code.

start_io() None[source]

Start the account I/O.

stop_io() None[source]

Stop the account I/O.

update_config(**kwargs) None[source]

Update config values.

wait_for_event(event_type=None) AttrDict[source]

Wait until the next event and return it.

wait_for_incoming_msg()[source]

Wait for incoming message and return it.

Consumes all events before the next incoming message event.

wait_for_incoming_msg_event()[source]

Wait for incoming message event and return it.

wait_for_msgs_changed_event()[source]

Wait for messages changed event and return it.

wait_for_msgs_noticed_event()[source]

Wait for messages noticed event and return it.

wait_for_reactions_changed()[source]

Wait for reaction change event.

wait_for_securejoin_inviter_success()[source]

Wait until SecureJoin process finishes successfully on the inviter side.

wait_for_securejoin_joiner_success()[source]

Wait until SecureJoin process finishes successfully on the joiner side.

wait_next_messages() list[Message][source]

Wait for new messages and return a list of them.

class deltachat_rpc_client.AttrDict(*args, **kwargs)[source]

Dictionary that allows accessing values using the “dot notation” as attributes.

class deltachat_rpc_client.Bot(account: Account, hooks: Iterable[tuple[Callable, type | EventFilter]] | None = None, logger: logging.Logger | None = None)[source]

Simple bot implementation that listens to events of a single account.

configure(email: str, password: str, **kwargs) None[source]

Configure the bot.

class deltachat_rpc_client.Chat(account: Account, id: int)[source]

Chat object which manages members and through which you can send and retrieve messages.

accept() None[source]

Accept this contact request chat.

add_contact(*contact: int | str | Contact) None[source]

Add contacts to this group.

archive() None[source]

Archive this chat.

block() None[source]

Block this chat.

can_send() bool[source]

Return true if messages can be sent to the chat.

delete() None[source]

Delete this chat and all its messages.

Note:

  • does not delete messages on server

  • the chat or contact is not blocked, new message will arrive

forward_messages(messages: list[Message]) None[source]

Forward a list of messages to this chat.

get_basic_snapshot() AttrDict[source]

Get a chat snapshot with basic info about this chat.

get_contacts() list[Contact][source]

Get the contacts belonging to this chat.

For single/direct chats self-address is not included.

get_draft() AttrDict | None[source]

Get draft message.

get_encryption_info() str[source]

Return encryption info for this chat.

get_fresh_message_count() int[source]

Get number of fresh messages in this chat.

get_full_snapshot() AttrDict[source]

Get a full snapshot of this chat.

get_locations(contact: Contact | None = None, timestamp_from: 'datetime' | None = None, timestamp_to: 'datetime' | None = None) list[AttrDict][source]

Get list of location snapshots for the given contact in the given timespan.

get_messages(info_only: bool = False, add_daymarker: bool = False) list[Message][source]

Get the list of messages in this chat.

get_past_contacts() list[Contact][source]

Get past contacts for this chat.

get_qr_code() str[source]

Get Join-Group QR code text.

get_qr_code_svg() tuple[str, str][source]

Get Join-Group QR code text and SVG data.

leave() None[source]

Leave this chat.

mark_noticed() None[source]

Mark all messages in this chat as noticed.

mute(duration: int | None = None) None[source]

Mute this chat, if a duration is not provided the chat is muted forever.

Parameters:

duration – mute duration from now in seconds. Must be greater than zero.

pin() None[source]

Pin this chat.

remove_contact(*contact: int | str | Contact) None[source]

Remove members from this group.

remove_draft() None[source]

Remove draft message.

remove_image() None[source]

Remove profile image of this chat.

send_contact(contact: Contact)[source]

Send contact to the chat.

send_file(path)[source]

Send a file and return the resulting Message instance.

send_message(text: str | None = None, html: str | None = None, viewtype: ViewType | None = None, file: str | None = None, filename: str | None = None, location: tuple[float, float] | None = None, override_sender_name: str | None = None, quoted_msg: int | Message | None = None) Message[source]

Send a message and return the resulting Message instance.

send_sticker(path: str) Message[source]

Send an sticker and return the resulting Message instance.

send_text(text: str) Message[source]

Send a text message and return the resulting Message instance.

send_videochat_invitation() Message[source]

Send a videochat invitation and return the resulting Message instance.

set_draft(text: str | None = None, file: str | None = None, filename: str | None = None, quoted_msg: int | None = None, viewtype: str | None = None) None[source]

Set draft message.

set_ephemeral_timer(timer: int) None[source]

Set ephemeral timer of this chat in seconds.

0 means the timer is disabled, use 1 for immediate deletion.

set_image(path: str) None[source]

Set profile image of this chat.

Parameters:

path – Full path of the image to use as the group image.

set_name(name: str) None[source]

Set name of this chat.

unarchive() None[source]

Unarchive this chat.

unmute() None[source]

Unmute this chat.

unpin() None[source]

Unpin this chat.

class deltachat_rpc_client.Client(account: Account, hooks: Iterable[tuple[Callable, type | EventFilter]] | None = None, logger: logging.Logger | None = None)[source]

Simple Delta Chat client that listen to events of a single account.

add_hook(hook: ~typing.Callable, event: type | ~deltachat_rpc_client.events.EventFilter = <class 'deltachat_rpc_client.events.RawEvent'>) None[source]

Register hook for the given event filter.

add_hooks(hooks: Iterable[tuple[Callable, type | EventFilter]]) None[source]

Register multiple hooks.

configure(email: str, password: str, **kwargs) None[source]

Configure the client.

is_configured() bool[source]

Return True if the client is configured.

remove_hook(hook: Callable, event: type | EventFilter) None[source]

Unregister hook from the given event filter.

run_forever() None[source]

Process events forever.

run_until(func: Callable[[AttrDict], bool]) AttrDict[source]

Process events until the given callable evaluates to True.

The callable should accept an AttrDict object representing the last processed event. The event is returned when the callable evaluates to True.

class deltachat_rpc_client.Contact(account: Account, id: int)[source]

Contact API.

Essentially a wrapper for RPC, account ID and a contact ID.

block() None[source]

Block contact.

create_chat() Chat[source]

Create or get an existing 1:1 chat for this contact.

delete() None[source]

Delete contact.

get_encryption_info() str[source]

Get a multi-line encryption info.

Encryption info contains your fingerprint and the fingerprint of the contact.

get_snapshot() AttrDict[source]

Return a dictionary with a snapshot of all contact properties.

make_vcard() str[source]

Make a vCard for the contact.

reset_encryption() None[source]

Reset contact encryption.

set_name(name: str) None[source]

Change the name of this contact.

unblock() None[source]

Unblock contact.

class deltachat_rpc_client.DeltaChat(rpc: Rpc)[source]

Delta Chat accounts manager.

This is the root of the object oriented API.

add_account() Account[source]

Create a new account database.

get_all_accounts() list[Account][source]

Return a list of all available accounts.

get_system_info() AttrDict[source]

Get information about the Delta Chat core in this system.

maybe_network() None[source]

Indicate that the network conditions might have changed.

set_translations(translations: dict[str, str]) None[source]

Set stock translation strings.

start_io() None[source]

Start the I/O of all accounts.

stop_io() None[source]

Stop the I/O of all accounts.

class deltachat_rpc_client.EventType(*values)[source]

Core event types.

class deltachat_rpc_client.Message(account: Account, id: int)[source]

Delta Chat Message object.

continue_autocrypt_key_transfer(setup_code: str) None[source]

Continue the Autocrypt Setup Message key transfer.

This function can be called on received Autocrypt Setup Message to import the key encrypted with the provided setup code.

get_info() str[source]

Return message info.

get_reactions() AttrDict | None[source]

Get message reactions.

get_sender_contact() Contact[source]

Return sender contact.

get_snapshot() AttrDict[source]

Get a snapshot with the properties of this message.

get_webxdc_info() dict[source]

Get info from a Webxdc message in JSON format.

get_webxdc_status_updates(last_known_serial: int = 0) list[source]

Return a list of Webxdc status updates for Webxdc instance message.

mark_seen() None[source]

Mark the message as seen.

send_reaction(*reaction: str) Message[source]

Send a reaction to this message.

send_webxdc_status_update(update: dict | str, description: str) None[source]

Send a webxdc status update. This message must be a webxdc.

wait_until_delivered() None[source]

Consume events until the message is delivered.

class deltachat_rpc_client.SpecialContactId(*values)[source]

Special contact IDs.

class deltachat_rpc_client.Rpc(accounts_dir: str | None = None, **kwargs)[source]

RPC client.

clear_all_events(account_id: int)[source]

Remove all queued-up events for a given account. Useful for tests.

close() None[source]

Terminate RPC server process and wait until the reader loop finishes.

events_loop() None[source]

Request new events and distributes them between queues.

get_queue(account_id: int) Queue[source]

Get event queue corresponding to the given account ID.

reader_loop() None[source]

Process JSON-RPC responses from the RPC server process output.

start() None[source]

Start RPC server subprocess.

wait_for_event(account_id: int) dict | None[source]

Wait for the next event from the given account and returns it.

writer_loop() None[source]

Writer loop ensuring only a single thread writes requests.

deltachat_rpc_client.run_bot_cli(hooks: Iterable[Tuple[Callable, type | EventFilter]] | None = None, argv: list | None = None, **kwargs) None[source]

Run a simple bot command line using the given hooks.

Extra keyword arguments are passed to the internal Rpc object.

deltachat_rpc_client.run_client_cli(hooks: Iterable[Tuple[Callable, type | EventFilter]] | None = None, argv: list | None = None, **kwargs) None[source]

Run a simple command line app, using the given hooks.

Extra keyword arguments are passed to the internal Rpc object.