API Reference

Delta Chat JSON-RPC high-level API

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

Delta Chat account.

wait_for_event() → AttrDict

Wait until the next event and return it.

clear_all_events()

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

remove() → None

Remove the account.

start_io() → None

Start the account I/O.

stop_io() → None

Stop the account I/O.

get_info() → AttrDict

Return dictionary of this account configuration parameters.

get_size() → int

Get the combined filesize of an account in bytes.

is_configured() → bool

Return True if this account is configured.

set_config(key: str, value: str | None = None) → None

Set configuration value.

get_config(key: str) → str | None

Get configuration value.

update_config(**kwargs) → None

update config values.

set_avatar(img_path: str | None = None) → None

Set self avatar.

Passing None will discard the currently set avatar.

get_avatar() → str | None

Get self avatar.

bring_online()

Start I/O and wait until IMAP becomes IDLE.

create_contact(obj: int | str | Contact, name: str | None = None) → Contact

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 or contact id.

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

get_contact_by_id(contact_id: int) → Contact

Return Contact instance for the given contact ID.

get_contact_by_addr(address: str) → Contact | None

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

get_blocked_contacts() → list[AttrDict]

Return a list with snapshots of all blocked contacts.

get_chat_by_contact(contact: int | Contact) → Chat | None

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

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

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.

• only_verified – if True only return verified contacts.

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

property self_contact: Contact

This account’s identity as a Contact.

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]

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.

create_group(name: str, protect: bool = False) → Chat

Create a new group chat.

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

get_chat_by_id(chat_id: int) → Chat

Return the Chat instance with the given ID.

secure_join(qrdata: str) → Chat

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.

get_qr_code() → tuple[str, str]

Get Setup-Contact QR Code text and SVG data.

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_message_by_id(msg_id: int) → Message

Return the Message instance with the given ID.

mark_seen_messages(messages: list[Message]) → None

Mark the given set of messages as seen.

delete_messages(messages: list[Message]) → None

Delete messages (local and remote).

get_fresh_messages() → list[Message]

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_next_messages() → list[Message]

Return a list of next messages.

wait_next_messages() → list[Message]

Wait for new messages and return a list of them.

wait_for_incoming_msg_event()

Wait for incoming message event and return it.

get_fresh_messages_in_arrival_order() → list[Message]

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

export_backup(path, passphrase: str = '') → None

Export backup.

import_backup(path, passphrase: str = '') → None

Import backup.

export_self_keys(path) → None

Export keys.

import_self_keys(path) → None

Import keys.

class deltachat_rpc_client.AttrDict(*args, **kwargs)

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)

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

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

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

delete() → None

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

block() → None

Block this chat.

accept() → None

Accept this contact request chat.

leave() → None

Leave this chat.

mute(duration: int | None = None) → None

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.

unmute() → None

Unmute this chat.

pin() → None

Pin this chat.

unpin() → None

Unpin this chat.

archive() → None

Archive this chat.

unarchive() → None

Unarchive this chat.

set_name(name: str) → None

Set name of this chat.

set_ephemeral_timer(timer: int) → None

Set ephemeral timer of this chat in seconds.

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

get_encryption_info() → str

Return encryption info for this chat.

get_qr_code() → tuple[str, str]

Get Join-Group QR code text and SVG data.

get_basic_snapshot() → AttrDict

Get a chat snapshot with basic info about this chat.

get_full_snapshot() → AttrDict

Get a full snapshot of this chat.

can_send() → bool

Return true if messages can be sent to the chat.

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

Send a message and return the resulting Message instance.

send_text(text: str) → Message

Send a text message and return the resulting Message instance.

send_file(path)

Send a file and return the resulting Message instance.

send_videochat_invitation() → Message

Send a videochat invitation and return the resulting Message instance.

send_sticker(path: str) → Message

Send an sticker and return the resulting Message instance.

forward_messages(messages: list[Message]) → None

Forward a list of messages to this chat.

set_draft(text: str | None = None, file: str | None = None, quoted_msg: int | None = None, viewtype: str | None = None) → None

Set draft message.

remove_draft() → None

Remove draft message.

get_draft() → AttrDict | None

Get draft message.

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

get the list of messages in this chat.

get_fresh_message_count() → int

Get number of fresh messages in this chat

mark_noticed() → None

Mark all messages in this chat as noticed.

add_contact(*contact: int | str | Contact) → None

Add contacts to this group.

remove_contact(*contact: int | str | Contact) → None

Remove members from this group.

get_contacts() → list[Contact]

Get the contacts belonging to this chat.

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

set_image(path: str) → None

Set profile image of this chat.

Parameters:

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

remove_image() → None

Remove profile image of this chat.

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

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

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

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

Register hook for the given event filter.

remove_hook(hook: Callable, event: type | EventFilter) → None

Unregister hook from the given event filter.

run_forever() → None

Process events forever.

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

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)

Contact API.

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

block() → None

Block contact.

unblock() → None

Unblock contact.

delete() → None

Delete contact.

set_name(name: str) → None

Change the name of this contact.

get_encryption_info() → str

Get a multi-line encryption info, containing your fingerprint and the fingerprint of the contact.

get_snapshot() → AttrDict

Return a dictionary with a snapshot of all contact properties.

create_chat() → Chat

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

class deltachat_rpc_client.DeltaChat(rpc: Rpc)

Delta Chat accounts manager. This is the root of the object oriented API.

add_account() → Account

Create a new account database.

get_all_accounts() → list[Account]

Return a list of all available accounts.

start_io() → None

Start the I/O of all accounts.

stop_io() → None

Stop the I/O of all accounts.

maybe_network() → None

Indicate that the network likely has come back or just that the network conditions might have changed.

get_system_info() → AttrDict

Get information about the Delta Chat core in this system.

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

Set stock translation strings.

class deltachat_rpc_client.EventType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Core event types

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

Delta Chat Message object.

send_reaction(*reaction: str) → Message

Send a reaction to this message.

get_snapshot() → AttrDict

Get a snapshot with the properties of this message.

get_reactions() → AttrDict | None

Get message reactions.

mark_seen() → None

Mark the message as seen.

send_webxdc_status_update(update: dict | str, description: str) → None

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

wait_until_delivered() → None

Consume events until the message is delivered.

class deltachat_rpc_client.SpecialContactId(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

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

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

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

Extra keyword arguments are passed to the internal Rpc object.