API Reference
Delta Chat JSON-RPC high-level API.
- class deltachat_rpc_client.Account(manager: DeltaChat, id: int)[source]
Delta Chat account.
- check_qr(qr)[source]
Parse QR code contents.
This function takes the raw text scanned and checks what can be done with it.
- clone() Account [source]
Clone given account.
This uses backup-transfer via iroh, i.e. the ‘Add second device’ feature.
- create_broadcast(name: str) Chat [source]
Create a new broadcast channel (called “Channel” in the UI).
Broadcast channels are similar to groups on the sending device, however, recipients get the messages in a read-only chat and will not see who the other members are.
Called broadcast here rather than channel, because the word “channel” already appears a lot in the code, which would make it hard to grep for it.
After creation, the chat contains no recipients and is in _unpromoted_ state; see create_group() for more information on the unpromoted state.
Returns the created chat.
- 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 one member (see SpecialContactId.SELF) and is in _unpromoted_ state. This means, you can add or remove members, change the name, the group image and so on without messages being sent to all group members.
This changes as soon as the first message is sent to the group members and the group becomes _promoted_. After that, all changes are synced with all group members by sending status message.
To check, if a chat is still unpromoted, you can look at the is_unpromoted property of a chat (see get_full_snapshot() / get_basic_snapshot()). This may be useful if you want to show some help for just created groups.
- Parameters:
protect – If set to 1 the function creates group with protection initially enabled. Only verified members are allowed in these groups and end-to-end-encryption is always enabled.
- 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_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_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_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_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.
- import_vcard(vcard: str) list[Contact] [source]
Import vCard.
Return created or modified contacts in the order they appear in vCard.
- 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.
- set_avatar(img_path: str | None = None) None [source]
Set self avatar.
Passing None will discard the currently set avatar.
- wait_for_incoming_msg()[source]
Wait for incoming message and return it.
Consumes all events before the next incoming message event.
- wait_for_securejoin_inviter_success()[source]
Wait until SecureJoin process finishes successfully on the inviter side.
- 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.
- class deltachat_rpc_client.Chat(account: Account, id: int)[source]
Chat object which manages members and through which you can send and retrieve messages.
- 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
- get_contacts() list[Contact] [source]
Get the contacts belonging to this chat.
For single/direct chats self-address is not included.
- 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.
- 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.
- 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.
- 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.
- class deltachat_rpc_client.Contact(account: Account, id: int)[source]
Contact API.
Essentially a wrapper for RPC, account ID and a contact ID.
- class deltachat_rpc_client.DeltaChat(rpc: Rpc)[source]
Delta Chat accounts manager.
This is the root of the object oriented API.
- 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_webxdc_status_updates(last_known_serial: int = 0) list [source]
Return a list of Webxdc status updates for Webxdc instance message.
- 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.