Delta Chat JSON-RPC Bindings

https://py.delta.chat/jsonrpc/
Admin
Delta Chat JSON-RPC Bindings provide Python interfaces for interacting with the Delta Chat core via...
Tokens:13,178
Snippets:89
Trust Score:9.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Build and Install deltachat-rpc-server from Source

Source: https://py.delta.chat/jsonrpc/install

Builds and installs the `deltachat-rpc-server` binary from its source code repository using Cargo. Requires Rust and Cargo to be installed.

```shell
cargo install --git https://github.com/chatmail/core/ deltachat-rpc-server
```

--------------------------------

### Verify deltachat-rpc-server Installation

Source: https://py.delta.chat/jsonrpc/install

Checks if the `deltachat-rpc-server` binary is installed correctly and displays its version. This confirms the installation was successful.

```shell
deltachat-rpc-server --version
```

--------------------------------

### Install deltachat-rpc-server from PyPI

Source: https://py.delta.chat/jsonrpc/install

Installs the `deltachat-rpc-server` binary from the Python Package Index (PyPI). This is the recommended method for obtaining the server.

```shell
pip install deltachat-rpc-server
```

--------------------------------

### Python REPL Example for Delta Chat RPC

Source: https://py.delta.chat/jsonrpc/develop

Demonstrates how to use the Python REPL to interact with Delta Chat's RPC client. It shows how to instantiate the Rpc client, start it, create a DeltaChat instance, get system information, and close the connection.

```python
$ python
>>> from deltachat_rpc_client import *
>>> rpc = Rpc()
>>> rpc.start()
>>> dc = DeltaChat(rpc)
>>> system_info = dc.get_system_info()
>>> system_info["level"]
'awesome'
>>> rpc.close()
```

--------------------------------

### Echo Bot Example (Python)

Source: https://py.delta.chat/jsonrpc/examples

A basic example of an echo bot that sends back any received text message. It demonstrates how to set up an account, process incoming messages, and handle events without using hooks. Requires email and password as command-line arguments for account configuration.

```python
#!/usr/bin/env python3
"""
Example echo bot without using hooks
"""

import logging
import sys

from deltachat_rpc_client import DeltaChat, EventType, Rpc, SpecialContactId


def main():
    with Rpc() as rpc:
        deltachat = DeltaChat(rpc)
        system_info = deltachat.get_system_info()
        logging.info("Running deltachat core %s", system_info["deltachat_core_version"])

        accounts = deltachat.get_all_accounts()
        account = accounts[0] if accounts else deltachat.add_account()

        account.set_config("bot", "1")
        if not account.is_configured():
            logging.info("Account is not configured, configuring")
            account.set_config("addr", sys.argv[1])
            account.set_config("mail_pw", sys.argv[2])
            account.configure()
            logging.info("Configured")
        else:
            logging.info("Account is already configured")
            deltachat.start_io()

        def process_messages():
            for message in account.get_next_messages():
                snapshot = message.get_snapshot()
                if snapshot.from_id != SpecialContactId.SELF and not snapshot.is_bot and not snapshot.is_info:
                    snapshot.chat.send_text(snapshot.text)
                snapshot.message.mark_seen()

        # Process old messages.
        process_messages()

        while True:
            event = account.wait_for_event()
            if event["kind"] == EventType.INFO:
                logging.info("%s", event["msg"])
            elif event["kind"] == EventType.WARNING:
                logging.warning("%s", event["msg"])
            elif event["kind"] == EventType.ERROR:
                logging.error("%s", event["msg"])
            elif event["kind"] == EventType.INCOMING_MSG:
                logging.info("Got an incoming message")
                process_messages()


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    main()

```

--------------------------------

### Install deltachat-rpc-client from Source

Source: https://py.delta.chat/jsonrpc/install

Installs the `deltachat-rpc-client` Python package directly from the main branch of its GitHub repository. This is useful for using the latest development version.

```shell
pip install git+https://github.com/chatmail/core.git@main#subdirectory=deltachat-rpc-client
```

--------------------------------

### Install deltachat-rpc-client from PyPI

Source: https://py.delta.chat/jsonrpc/install

Installs the `deltachat-rpc-client` Python package from the Python Package Index (PyPI). This package provides the client-side interface for the JSON-RPC server.

```shell
pip install deltachat-rpc-client
```

--------------------------------

### Advanced Echo Bot with Hooks Example (Python)

Source: https://py.delta.chat/jsonrpc/examples

An advanced echo bot example utilizing the Delta Chat RPC client's hook system. It echoes messages with non-empty text, supports a '/help' command, and logs various event types including member list changes, group image changes, and group name changes. Requires email and password as command-line arguments for account configuration.

```python
#!/usr/bin/env python3
"""Advanced echo bot example.

it will echo back any message that has non-empty text and also supports the /help command.
"""

import logging
import sys
from threading import Thread

from deltachat_rpc_client import Bot, DeltaChat, EventType, Rpc, events

hooks = events.HookCollection()


@hooks.on(events.RawEvent)
def log_event(event):
    if event.kind == EventType.INFO:
        logging.info(event.msg)
    elif event.kind == EventType.WARNING:
        logging.warning(event.msg)


@hooks.on(events.RawEvent(EventType.ERROR))
def log_error(event):
    logging.error(event.msg)


@hooks.on(events.MemberListChanged)
def on_memberlist_changed(event):
    logging.info("member %s was %s", event.member, "added" if event.member_added else "removed")


@hooks.on(events.GroupImageChanged)
def on_group_image_changed(event):
    logging.info("group image %s", "deleted" if event.image_deleted else "changed")


@hooks.on(events.GroupNameChanged)
def on_group_name_changed(event):
    logging.info("group name changed, old name: %s", event.old_name)


@hooks.on(events.NewMessage(func=lambda e: not e.command))
def echo(event):
    snapshot = event.message_snapshot
    if snapshot.text or snapshot.file:
        snapshot.chat.send_message(text=snapshot.text, file=snapshot.file)


@hooks.on(events.NewMessage(command="/help"))
def help_command(event):
    snapshot = event.message_snapshot
    snapshot.chat.send_text("Send me any message and I will echo it back")


def main():
    with Rpc() as rpc:
        deltachat = DeltaChat(rpc)
        system_info = deltachat.get_system_info()
        logging.info("Running deltachat core %s", system_info.deltachat_core_version)

        accounts = deltachat.get_all_accounts()
        account = accounts[0] if accounts else deltachat.add_account()

        bot = Bot(account, hooks)
        if not bot.is_configured():
            configure_thread = Thread(run=bot.configure, kwargs={"email": sys.argv[1], "password": sys.argv[2]})
            configure_thread.start()
        bot.run_forever()


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    main()

```

--------------------------------

### Create and Activate Virtual Environment

Source: https://py.delta.chat/jsonrpc/install

This code snippet demonstrates how to create a Python virtual environment and activate it. This is a common practice for managing project dependencies.

```shell
python -m venv venv
. venv/bin/activate
```

--------------------------------

### Start Account Input/Output

Source: https://py.delta.chat/jsonrpc/reference

Initiates the background processes responsible for handling incoming and outgoing messages and events for the account. Essential for real-time functionality.

```python
start_io() → None[source]
```

--------------------------------

### Echo Bot with Hooks Example (Python)

Source: https://py.delta.chat/jsonrpc/examples

A minimal echo bot using the Delta Chat RPC client's hook system. It echoes back any text message received and logs all Delta Chat core events to the console. This approach simplifies bot development by abstracting event handling.

```python
#!/usr/bin/env python3
"""Minimal echo bot example.

it will echo back any text send to it, it also will print to console all Delta Chat core events.
Pass --help to the CLI to see available options.
"""

from deltachat_rpc_client import events, run_bot_cli

hooks = events.HookCollection()


@hooks.on(events.RawEvent)
def log_event(event):
    print(event)


@hooks.on(events.NewMessage)
def echo(event):
    snapshot = event.message_snapshot
    snapshot.chat.send_text(snapshot.text)


if __name__ == "__main__":
    run_bot_cli(hooks)

```

--------------------------------

### Set Configuration from QR Code

Source: https://py.delta.chat/jsonrpc/reference

Applies account configuration settings by parsing data from a QR code. Useful for quick setup or transferring settings.

```python
set_config_from_qr(_qr : str_)[source]
```

--------------------------------

### Get Setup-Contact QR Code Text

Source: https://py.delta.chat/jsonrpc/reference

Generates and returns the text content for a Setup-Contact QR code. This data is used to transfer account information to another Delta Chat account, often via a visual scan.

```python
get_qr_code() → str[source]
```

--------------------------------

### Get Setup-Contact QR Code SVG

Source: https://py.delta.chat/jsonrpc/reference

Retrieves both the text content and the SVG representation of a Setup-Contact QR code. Useful for applications that need to display the QR code visually.

```python
get_qr_code_svg() → tuple[str, str][source]
```

--------------------------------

### Initiate Autocrypt Key Transfer

Source: https://py.delta.chat/jsonrpc/reference

Sends an Autocrypt Setup Message to initiate or continue the key exchange process for end-to-end encryption. This function is key for establishing secure communication channels.

```python
initiate_autocrypt_key_transfer() → None[source]
```

--------------------------------

### Get Account Configuration

Source: https://py.delta.chat/jsonrpc/reference

Returns a dictionary containing the configuration parameters of the current account. This provides insights into account settings and operational status.

```python
get_info() → AttrDict[source]
```

--------------------------------

### DeltaChat RPC Client: Control RPC Server Lifecycle

Source: https://py.delta.chat/jsonrpc/reference

Functions for managing the lifecycle of the Delta Chat RPC server. `start` initializes and begins the RPC server subprocess, while `reader_loop` processes incoming JSON-RPC responses. `writer_loop` ensures sequential writing of requests to prevent concurrency issues.

```python
start() → None[source]
    
    Start RPC server subprocess.

reader_loop() → None[source]
    
    Process JSON-RPC responses from the RPC server process output.

writer_loop() → None[source]
    
    Writer loop ensuring only a single thread writes requests.
```

--------------------------------

### Get Account Size

Source: https://py.delta.chat/jsonrpc/reference

Returns the total combined filesize of the account in bytes. Useful for monitoring storage usage.

```python
get_size() → int[source]
```

--------------------------------

### Get Next Set of Messages

Source: https://py.delta.chat/jsonrpc/reference

Retrieves the subsequent batch of messages. This function is typically used for pagination or loading more messages in a conversation history.

```python
get_next_messages() → list[Message][source]
```

--------------------------------

### Get Contact Information by ID

Source: https://py.delta.chat/jsonrpc/reference

Retrieves a Contact instance using its unique identifier. This is a primary method for accessing specific contact details within the Delta Chat system.

```python
get_contact_by_id(_contact_id : int_) → Contact[source]
```

--------------------------------

### Message Retrieval and Sending in Python

Source: https://py.delta.chat/jsonrpc/reference

Enables retrieving messages from a chat, including options to get only info or include day markers. It also supports sending various types of messages such as text, files, stickers, and video chat invitations.

```python
messages = chat.get_messages()
info_messages = chat.get_messages(_info_only=True)
fresh_count = chat.get_fresh_message_count()
chat.send_message(text='Hello')
chat.send_file('/path/to/file.txt')
chat.send_sticker('/path/to/sticker.webp')
chat.send_videochat_invitation()
```

--------------------------------

### Python: Get Contact by Address

Source: https://py.delta.chat/jsonrpc/reference

Looks up a known and unblocked contact by their email address. This is useful for retrieving a Contact object for a specific user if their address is known.

```python
def get_contact_by_addr(_address : str_) → Contact | None:
    """
    Looks up a known and unblocked contact with a given e-mail address. To get a list of all known and unblocked contacts, use contacts_get_contacts().
    """
    pass
```

--------------------------------

### Python: Get Chat List

Source: https://py.delta.chat/jsonrpc/reference

Retrieves a list of chats, with various filtering and sorting options. It can return full Chat instances or snapshots, and supports filtering by query, contact, archived status, and special chat types.

```python
def 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.
    """
    pass
```

--------------------------------

### Contact Management in Python

Source: https://py.delta.chat/jsonrpc/reference

Manages contacts within a chat, allowing adding new contacts and retrieving existing ones. It also provides functionality to get past contacts associated with the chat.

```python
chat.add_contact(contact_id_or_object)
contacts = chat.get_contacts()
past_contacts = chat.get_past_contacts()
```

--------------------------------

### Configure and Run Delta Chat Client

Source: https://py.delta.chat/jsonrpc/reference

Provides methods to configure the Delta Chat client with account credentials, check its configuration status, and manage event processing.

```python
configure(_email : str_, _password : str_, _** kwargs_) → None[source]
    
    Configure the client.

is_configured() → bool[source]
    
    Return True if the client is configured.

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.
```

--------------------------------

### Account and Configuration

Source: https://py.delta.chat/jsonrpc/reference

APIs for managing account settings, configuration, and status.

```APIDOC
## get_info

### Description
Return dictionary of this account configuration parameters.

### Method
GET

### Endpoint
/get_info

### Response
#### Success Response (200)
- **AttrDict** (object) - A dictionary containing account configuration parameters.

### Response Example
{
  "info": {
    "username": "user@example.com",
    "server": "delta.im"
  }
}

## get_size

### Description
Get the combined filesize of an account in bytes.

### Method
GET

### Endpoint
/get_size

### Response
#### Success Response (200)
- **int** - The total size of the account in bytes.

### Response Example
{
  "size": 1024000
}

## import_backup

### Description
Import backup.

### Method
POST

### Endpoint
/import_backup

### Parameters
#### Request Body
- **path** (str) - Required - The path to the backup file.
- **passphrase** (str) - Optional - The passphrase for the backup. Defaults to an empty string.

### Request Example
{
  "path": "/path/to/backup.zip",
  "passphrase": "mysecret"
}

## import_self_keys

### Description
Import keys.

### Method
POST

### Endpoint
/import_self_keys

### Parameters
#### Request Body
- **path** (str) - Required - The path to the keys file.

### Request Example
{
  "path": "/path/to/keys.json"
}

## is_configured

### Description
Return True if this account is configured.

### Method
GET

### Endpoint
/is_configured

### Response
#### Success Response (200)
- **bool** - True if the account is configured, False otherwise.

### Response Example
{
  "configured": true
}

## remove

### Description
Remove the account.

### Method
DELETE

### Endpoint
/remove

## set_config

### Description
Set configuration value.

### Method
POST

### Endpoint
/set_config

### Parameters
#### Request Body
- **key** (str) - Required - The configuration key.
- **value** (str | None) - Optional - The configuration value. Use None to remove the configuration.

### Request Example
{
  "key": "notification_sound",
  "value": "default.wav"
}

## set_config_from_qr

### Description
Set configuration values from a QR code.

### Method
POST

### Endpoint
/set_config_from_qr

### Parameters
#### Request Body
- **qr** (str) - Required - The QR code data.

### Request Example
{
  "qr": "delta_chat_config_qr_data"
}

## start_io

### Description
Start the account I/O.

### Method
POST

### Endpoint
/start_io

## stop_io

### Description
Stop the account I/O.

### Method
POST

### Endpoint
/stop_io

## update_config

### Description
Update config values.

### Method
POST

### Endpoint
/update_config

### Parameters
#### Request Body
- **kwargs** (object) - Required - Key-value pairs of configuration settings to update.

### Request Example
{
  "new_setting": "new_value",
  "another_setting": "another_value"
}
```

--------------------------------

### Bot Configuration in Python

Source: https://py.delta.chat/jsonrpc/reference

Configures the Delta Chat bot with email and password credentials. Supports additional keyword arguments for further customization.

```python
bot.configure(_email='user@example.com', _password='password')
```

--------------------------------

### DeltaChat RPC Client: Run Client CLI

Source: https://py.delta.chat/jsonrpc/reference

Facilitates running a generic command-line application using the RPC client with provided hooks. Additional keyword arguments are forwarded to the internal `Rpc` object. Suitable for building custom Delta Chat client applications.

```python
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.
      *[*]: Keyword-only parameters separator (PEP 3102)
```

--------------------------------

### DeltaChat RPC Client: Run Bot CLI

Source: https://py.delta.chat/jsonrpc/reference

Enables running a bot command-line interface with customizable hooks. Extra keyword arguments are passed to the internal `Rpc` object. Useful for creating interactive bots or testing bot logic.

```python
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.
```

--------------------------------

### Account Management API

Source: https://py.delta.chat/jsonrpc/reference

APIs for managing Delta Chat accounts, including account creation, cloning, and configuration.

```APIDOC
## Account Class

### Description
Represents a Delta Chat account.

### Methods

#### `bring_online()`
- **Description**: Starts I/O and waits until IMAP becomes IDLE.
- **Method**: POST
- **Endpoint**: `/account/bring_online`

#### `clear_all_events()`
- **Description**: Removes all queued-up events for a given account. Useful for tests.
- **Method**: POST
- **Endpoint**: `/account/clear_all_events`

#### `clone()`
- **Description**: Clones the given account using backup-transfer via iroh (Add second device feature).
- **Method**: POST
- **Endpoint**: `/account/clone`
- **Returns**: Cloned Account object.

#### `export_backup(path: str, passphrase: str = '')`
- **Description**: Exports the account backup to the specified path.
- **Method**: POST
- **Endpoint**: `/account/export_backup`
- **Parameters**:
  - **path** (str) - Required - The path to save the backup.
  - **passphrase** (str) - Optional - The passphrase for backup encryption.

#### `export_self_keys(path: str)`
- **Description**: Exports the account's self keys to the specified path.
- **Method**: POST
- **Endpoint**: `/account/export_self_keys`
- **Parameters**:
  - **path** (str) - Required - The path to save the keys.

#### `get_avatar() -> str | None`
- **Description**: Retrieves the account's avatar.
- **Method**: GET
- **Endpoint**: `/account/get_avatar`
- **Returns**: Avatar image URL or None.

#### `get_config(key: str)`
- **Description**: Retrieves a configuration value for the account.
- **Method**: GET
- **Endpoint**: `/account/get_config`
- **Parameters**:
  - **key** (str) - Required - The configuration key.
- **Returns**: Configuration value or None.
```

--------------------------------

### Clone Delta Chat Core Repository

Source: https://py.delta.chat/jsonrpc/develop

Clones the main Delta Chat core repository from GitHub, which is necessary for developing JSON-RPC bindings. This is the initial step in setting up the development environment.

```shell
git clone https://github.com/chatmail/core.git
```

--------------------------------

### Manage Delta Chat Accounts

Source: https://py.delta.chat/jsonrpc/reference

Provides functionalities for managing Delta Chat accounts, including creating new accounts, retrieving all accounts, and interacting with system information.

```python
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.
```

--------------------------------

### WebRTC and Events

Source: https://py.delta.chat/jsonrpc/reference

APIs for WebRTC server configuration and waiting for various events.

```APIDOC
## ice_servers

### Description
Return ICE servers for WebRTC configuration.

### Method
GET

### Endpoint
/ice_servers

### Response
#### Success Response (200)
- **list** - A list of ICE server configurations.

### Response Example
{
  "ice_servers": [
    {
      "urls": [
        "stun:stun.l.google.com:19302"
      ]
    }
  ]
}

## wait_for_event

### Description
Wait until the next event and return it.

### Method
GET

### Endpoint
/wait_for_event

### Parameters
#### Query Parameters
- **event_type** (str | None) - Optional - The type of event to wait for. If None, waits for any event.

### Response
#### Success Response (200)
- **AttrDict** (object) - An object representing the event.

### Response Example
{
  "event": {
    "type": "message_received",
    "data": {
      "id": 102,
      "sender": "Charlie",
      "text": "How are you?"
    }
  }
}

## wait_for_incoming_msg

### Description
Wait for incoming message and return it. Consumes all events before the next incoming message event.

### Method
GET

### Endpoint
/wait_for_incoming_msg

### Response
#### Success Response (200)
- **Message** (object) - The incoming Message object.

### Response Example
{
  "message": {
    "id": 102,
    "sender": "Charlie",
    "text": "How are you?"
  }
}

## wait_for_incoming_msg_event

### Description
Wait for incoming message event and return it.

### Method
GET

### Endpoint
/wait_for_incoming_msg_event

### Response
#### Success Response (200)
- **AttrDict** (object) - An object representing the incoming message event.

### Response Example
{
  "event": {
    "type": "message_received",
    "data": {
      "id": 102,
      "sender": "Charlie",
      "text": "How are you?"
    }
  }
}

## wait_for_msgs_changed_event

### Description
Wait for messages changed event and return it.

### Method
GET

### Endpoint
/wait_for_msgs_changed_event

### Response
#### Success Response (200)
- **AttrDict** (object) - An object representing the messages changed event.

### Response Example
{
  "event": {
    "type": "messages_changed"
  }
}

## wait_for_msgs_noticed_event

### Description
Wait for messages noticed event and return it.

### Method
GET

### Endpoint
/wait_for_msgs_noticed_event

### Response
#### Success Response (200)
- **AttrDict** (object) - An object representing the messages noticed event.

### Response Example
{
  "event": {
    "type": "messages_noticed"
  }
}

## wait_for_reactions_changed

### Description
Wait for reaction change event.

### Method
GET

### Endpoint
/wait_for_reactions_changed

### Response
#### Success Response (200)
- **AttrDict** (object) - An object representing the reaction change event.

### Response Example
{
  "event": {
    "type": "reactions_changed"
  }
}

## wait_for_securejoin_inviter_success

### Description
Wait until SecureJoin process finishes successfully on the inviter side.

### Method
GET

### Endpoint
/wait_for_securejoin_inviter_success

### Response
#### Success Response (200)
- **AttrDict** (object) - An object indicating the success of the SecureJoin process.

### Response Example
{
  "status": "success"
}
```

--------------------------------

### Import Account Backup

Source: https://py.delta.chat/jsonrpc/reference

Imports an account backup from a specified file path. An optional passphrase can be provided for encrypted backups.

```python
import_backup(_path_ , _passphrase : str = ''_) → None[source]
```

--------------------------------

### Chat and Utilities

Source: https://py.delta.chat/jsonrpc/reference

APIs related to chat operations, QR codes, and utility functions.

```APIDOC
## get_device_chat

### Description
Return device chat.

### Method
GET

### Endpoint
/get_device_chat

### Response
#### Success Response (200)
- **Chat** (object) - The device chat object.

### Response Example
{
  "chat": {
    "id": 5,
    "name": "Device Chat"
  }
}

## get_qr_code

### Description
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.

### Method
GET

### Endpoint
/get_qr_code

### Response
#### Success Response (200)
- **str** - The QR code text.

### Response Example
{
  "qr_code": "delta_chat_setup_data"
}

## get_qr_code_svg

### Description
Get Setup-Contact QR code text and SVG.

### Method
GET

### Endpoint
/get_qr_code_svg

### Response
#### Success Response (200)
- **tuple[str, str]** - A tuple containing the QR code text and its SVG representation.

### Response Example
{
  "qr_code_data": [
    "delta_chat_setup_data",
    "<svg>...</svg>"
  ]
}

## initiate_autocrypt_key_transfer

### Description
Send Autocrypt Setup Message.

### Method
POST

### Endpoint
/initiate_autocrypt_key_transfer

## secure_join

### Description
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.

### Method
POST

### Endpoint
/secure_join

### Parameters
#### Request Body
- **qrdata** (str) - Required - The text of the scanned QR code.

### Request Example
{
  "qrdata": "secure_join_qr_data"
}

### Response
#### Success Response (200)
- **Chat** (object) - The Chat object for the secure join session.

### Response Example
{
  "chat": {
    "id": 6,
    "name": "Secure Group"
  }
}
```

--------------------------------

### Secure Join Protocol

Source: https://py.delta.chat/jsonrpc/reference

Initiates or continues a SecureJoin protocol using QR code data. This function is used for securely onboarding devices or joining verified groups, with background handshake processing.

```python
secure_join(_qrdata : str_) → Chat[source]
```

--------------------------------

### QR Code and Event Handling API

Source: https://py.delta.chat/jsonrpc/reference

APIs for parsing QR codes and managing events.

```APIDOC
## Utility Functions

### Description
Utility functions for handling QR codes and events.

### Methods

#### `check_qr(qr: str)`
- **Description**: Parses QR code content and determines possible actions.
- **Method**: POST
- **Endpoint**: `/util/check_qr`
- **Parameters**:
  - **qr** (str) - Required - The raw text content of the QR code.

#### `get_all_events()`
- **Description**: Retrieves all queued-up events for the account.
- **Method**: GET
- **Endpoint**: `/event/get_all`
- **Returns**: A list of events.
```

--------------------------------

### AttrDict Usage in Python

Source: https://py.delta.chat/jsonrpc/reference

Demonstrates the use of AttrDict, a dictionary subclass that allows accessing values using dot notation.

```python
attr_dict = AttrDict({'key': 'value'})
value = attr_dict.key
```

--------------------------------

### Chat and Contact Management API

Source: https://py.delta.chat/jsonrpc/reference

APIs for creating, managing, and retrieving chats and contacts.

```APIDOC
## Chat and Contact Operations

### Description
Provides functionalities for creating and managing chats and contacts within Delta Chat.

### Methods

#### `create_broadcast(name: str) -> Chat`
- **Description**: Creates a new broadcast channel. Recipients receive messages in a read-only chat without seeing other members. The chat is initially unpromoted.
- **Method**: POST
- **Endpoint**: `/chat/create_broadcast`
- **Parameters**:
  - **name** (str) - Required - The name of the broadcast channel.
- **Returns**: The created Chat object.

#### `create_chat(account: Account) -> Chat`
- **Description**: Creates a new 1:1 chat with another account.
- **Method**: POST
- **Endpoint**: `/chat/create_chat`
- **Parameters**:
  - **account** (Account) - Required - The account to create a chat with.
- **Returns**: The created Chat object.

#### `create_contact(obj: int | str | Contact | Account, name: str | None = None) -> Contact`
- **Description**: Creates a new contact or returns an existing one. If a contact with the same email exists, it's unblocked and its display name is updated if provided.
- **Method**: POST
- **Endpoint**: `/contact/create`
- **Parameters**:
  - **obj** (int | str | Contact | Account) - Required - Email address, contact ID, or account.
  - **name** (str | None) - Optional - Display name for the contact.
- **Returns**: The created or existing Contact object.

#### `create_group(name: str, protect: bool = False) -> Chat`
- **Description**: Creates a new group chat. Initially, the group only has the creator as a member and is in an unpromoted state, allowing changes without notifying members. The group becomes promoted upon sending the first message.
- **Method**: POST
- **Endpoint**: `/chat/create_group`
- **Parameters**:
  - **name** (str) - Required - The name of the group.
  - **protect** (bool) - Optional - If True, creates the group with protection enabled (only verified members allowed, E2EE always enabled). Defaults to False.
- **Returns**: The created Chat object.

#### `get_blocked_contacts() -> list[AttrDict]`
- **Description**: Returns a list of snapshots for all blocked contacts.
- **Method**: GET
- **Endpoint**: `/contact/get_blocked`
- **Returns**: A list of blocked contact snapshots.

#### `get_chat_by_contact(contact: int | Contact) -> Chat | None`
- **Description**: Retrieves the 1:1 chat for a given contact if it exists.
- **Method**: GET
- **Endpoint**: `/chat/get_by_contact`
- **Parameters**:
  - **contact** (int | Contact) - Required - The contact to find the chat for.
- **Returns**: The Chat object or None if not found.

#### `get_chat_by_id(chat_id: int) -> Chat`
- **Description**: Retrieves the Chat instance with the specified ID.
- **Method**: GET
- **Endpoint**: `/chat/get_by_id`
- **Parameters**:
  - **chat_id** (int) - Required - The ID of the chat.
- **Returns**: The Chat object.

#### `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]`
- **Description**: Returns a list of chats, with optional filtering by query, contact, or archived status. Can return Chat instances or snapshots.
- **Method**: GET
- **Endpoint**: `/chat/list`
- **Parameters**:
  - **query** (str | None) - Optional - Filter chats by this query string.
  - **contact** (Contact | None) - Optional - Filter chats including this contact.
  - **archived_only** (bool) - Optional - If True, only return archived chats. Defaults to False.
  - **for_forwarding** (bool) - Optional - If True, sorts the list with "Saved messages" at the top and excludes "Device chat" and contact requests.
  - **no_specials** (bool) - Optional - If True, the archive link is not added to the list.
  - **alldone_hint** (bool) - Optional - If True, the "all done hint" special chat will be added as needed.
  - **snapshot** (bool) - Optional - If True, returns a list of chat snapshots instead of Chat instances. Defaults to False.
- **Returns**: A list of Chat objects or chat snapshots.

#### `get_contact_by_addr(address: str) -> Contact | None`
- **Description**: Looks up a known and unblocked contact by their email address.
- **Method**: GET
- **Endpoint**: `/contact/get_by_addr`
- **Parameters**:
  - **address** (str) - Required - The email address of the contact.
- **Returns**: The Contact object or None if not found.

#### `device_contact` (property)
- **Description**: Property to access the account's device contact.
- **Method**: GET
- **Endpoint**: `/account/device_contact`
- **Returns**: The device Contact object.
```

--------------------------------

### Retrieve ICE Servers for WebRTC

Source: https://py.delta.chat/jsonrpc/reference

Provides a list of ICE servers required for establishing WebRTC connections. Essential for real-time communication features.

```python
ice_servers() → list[source]
```

--------------------------------

### SecureJoin and Message Waiting in Python

Source: https://py.delta.chat/jsonrpc/reference

Includes functions to wait for the SecureJoin process to complete successfully on the joiner's side and to retrieve new messages.

```python
wait_for_securejoin_joiner_success()
new_messages = wait_next_messages()
```

--------------------------------

### Run Pytest Tests

Source: https://py.delta.chat/jsonrpc/develop

Executes the tests for the `deltachat-rpc-client` using the pytest framework. This command should be run after activating the development virtual environment.

```shell
pytest deltachat-rpc-client/tests/
```

--------------------------------

### Check Account Configuration Status

Source: https://py.delta.chat/jsonrpc/reference

Returns a boolean value indicating whether the account is configured and ready for use. Useful for checking prerequisites before performing account-related operations.

```python
is_configured() → bool[source]
```

--------------------------------

### Set Single Configuration Value

Source: https://py.delta.chat/jsonrpc/reference

Sets a specific configuration key-value pair for the account. Allows for granular control over account settings.

```python
set_config(_key : str_, _value : str | None = None_) → None[source]
```

--------------------------------

### Python: Create 1:1 Chat

Source: https://py.delta.chat/jsonrpc/reference

Creates a new one-on-one chat with another account. This is a fundamental operation for initiating direct communication between two users.

```python
def create_chat(_account : Account_) → Chat:
    """
    Create a 1:1 chat with another account. 
    """
    pass
```

--------------------------------

### Update Multiple Configuration Values

Source: https://py.delta.chat/jsonrpc/reference

Updates multiple account configuration values simultaneously using keyword arguments. Provides a convenient way to modify several settings at once.

```python
update_config(_** kwargs_) → None[source]
```

--------------------------------

### Activate Virtual Environment

Source: https://py.delta.chat/jsonrpc/develop

Activates a persistent virtual environment named 'venv'. This environment is created using the `scripts/make-rpc-testenv.sh` script and is used for running tests efficiently during development.

```shell
. venv/bin/activate
```

--------------------------------

### Fetch Fresh Messages (Arrival Order)

Source: https://py.delta.chat/jsonrpc/reference

Retrieves a list of fresh messages sorted by their arrival time, with ascending IDs. Recommended for bots and processes that need to handle messages in chronological order.

```python
get_fresh_messages_in_arrival_order() → list[Message][source]
```

--------------------------------

### Python: Export Backup

Source: https://py.delta.chat/jsonrpc/reference

Exports the account backup to a specified path. An optional passphrase can be provided for encrypting the backup.

```python
def export_backup(_path_ , _passphrase : str = ''_) → None:
    """
    Export backup.
    """
    pass
```

--------------------------------

### Contact Management

Source: https://py.delta.chat/jsonrpc/reference

APIs for retrieving, importing, and managing contacts within Delta Chat.

```APIDOC
## get_contact_by_id

### Description
Return Contact instance for the given contact ID.

### Method
GET

### Endpoint
/get_contact_by_id

### Parameters
#### Path Parameters
- **_contact_id** (int) - Required - The ID of the contact to retrieve.

### Response
#### Success Response (200)
- **Contact** (object) - The Contact instance.

### Response Example
{
  "contact": {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}

## get_contacts

### Description
Get a filtered list of contacts.

### Method
GET

### Endpoint
/get_contacts

### Parameters
#### Query Parameters
- **query** (str) - Optional - If a string is specified, only return contacts whose name or e-mail matches query.
- **with_self** (bool) - Optional - If True, the self-contact is also included if it matches the query. Defaults to False.
- **snapshot** (bool) - Optional - If True, return a list of contact snapshots instead of Contact instances. Defaults to False.

### Response
#### Success Response (200)
- **list[Contact | AttrDict]** - A list of Contact instances or their snapshots.

### Response Example
{
  "contacts": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane.smith@example.com"
    }
  ]
}

## import_vcard

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

### Method
POST

### Endpoint
/import_vcard

### Parameters
#### Request Body
- **vcard** (str) - Required - The vCard data as a string.

### Request Example
{
  "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nEMAIL:john.doe@example.com\nEND:VCARD"
}

### Response
#### Success Response (200)
- **list[Contact]** - A list of created or modified Contact instances.

### Response Example
{
  "contacts": [
    {
      "id": 3,
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  ]
}

## make_vcard

### Description
Create vCard with the given contacts.

### Method
POST

### Endpoint
/make_vcard

### Parameters
#### Request Body
- **contacts** (list[Contact]) - Required - A list of Contact instances to include in the vCard.

### Request Example
{
  "contacts": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  ]
}

### Response
#### Success Response (200)
- **str** - The generated vCard data as a string.

### Response Example
{
  "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nEMAIL:john.doe@example.com\nEND:VCARD"
}

## set_avatar

### Description
Set self avatar.
Passing None will discard the currently set avatar.

### Method
POST

### Endpoint
/set_avatar

### Parameters
#### Request Body
- **img_path** (str | None) - Optional - The path to the image file to set as the avatar. Use None to remove the avatar.

### Request Example
{
  "img_path": "/path/to/avatar.jpg"
}

## _property _self_contact 

### Description
Account’s identity as a Contact.

### Method
GET

### Endpoint
/self_contact

### Response
#### Success Response (200)
- **Contact** (object) - The self-contact object.

### Response Example
{
  "contact": {
    "id": 0,
    "name": "Me",
    "email": "me@example.com"
  }
}
```

--------------------------------

### QR Code Generation in Python

Source: https://py.delta.chat/jsonrpc/reference

Generates QR codes for joining groups, providing both the text representation and SVG data for visual display.

```python
qr_text = chat.get_qr_code()
qr_text, qr_svg = chat.get_qr_code_svg()
```

--------------------------------

### Draft and Image Management in Python

Source: https://py.delta.chat/jsonrpc/reference

Manages draft messages and profile images for a chat. This includes setting, removing drafts, and setting or removing the chat's profile image.

```python
chat.set_draft(text='Draft message')
chat.remove_draft()
chat.set_image('/path/to/image.png')
chat.remove_image()
```

--------------------------------

### Wait for SecureJoin Inviter Success

Source: https://py.delta.chat/jsonrpc/reference

Blocks until the SecureJoin process, initiated by the inviter, completes successfully. This is used on the device that was invited.

```python
wait_for_securejoin_inviter_success()[source]
```

--------------------------------

### Outgoing Call Placement in Python

Source: https://py.delta.chat/jsonrpc/reference

Initiates an outgoing call from the chat interface, requiring specific call information as input.

```python
chat.place_outgoing_call(_place_call_info='call_details')
```

--------------------------------

### Message Handling

Source: https://py.delta.chat/jsonrpc/reference

APIs for retrieving and managing messages, including fresh messages and specific messages by ID.

```APIDOC
## get_fresh_messages

### Description
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.

### Method
GET

### Endpoint
/get_fresh_messages

### Response
#### Success Response (200)
- **list[Message]** - A list of Message objects, sorted by newest first.

### Response Example
{
  "messages": [
    {
      "id": 101,
      "sender": "Alice",
      "text": "Hello!"
    },
    {
      "id": 100,
      "sender": "Bob",
      "text": "Hi Alice!"
    }
  ]
}

## get_fresh_messages_in_arrival_order

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

### Method
GET

### Endpoint
/get_fresh_messages_in_arrival_order

### Response
#### Success Response (200)
- **list[Message]** - A list of Message objects, sorted by arrival order.

### Response Example
{
  "messages": [
    {
      "id": 100,
      "sender": "Bob",
      "text": "Hi Alice!"
    },
    {
      "id": 101,
      "sender": "Alice",
      "text": "Hello!"
    }
  ]
}

## get_message_by_id

### Description
Return the Message instance with the given ID.

### Method
GET

### Endpoint
/get_message_by_id

### Parameters
#### Path Parameters
- **_msg_id** (int) - Required - The ID of the message to retrieve.

### Response
#### Success Response (200)
- **Message** (object) - The Message instance.

### Response Example
{
  "message": {
    "id": 101,
    "sender": "Alice",
    "text": "Hello!"
  }
}

## get_next_messages

### Description
Return a list of next messages.

### Method
GET

### Endpoint
/get_next_messages

### Response
#### Success Response (200)
- **list[Message]** - A list of next Message objects.

### Response Example
{
  "messages": [
    {
      "id": 102,
      "sender": "Charlie",
      "text": "How are you?"
    }
  ]
}

## mark_seen_messages

### Description
Mark the given set of messages as seen.

### Method
POST

### Endpoint
/mark_seen_messages

### Parameters
#### Request Body
- **messages** (list[Message]) - Required - A list of Message objects to mark as seen.

### Request Example
{
  "messages": [
    {
      "id": 101,
      "sender": "Alice",
      "text": "Hello!"
    }
  ]
}

```

--------------------------------

### Set Account Avatar

Source: https://py.delta.chat/jsonrpc/reference

Sets or removes the avatar image for the account. Passing a file path sets a new avatar, while passing None discards the current one.

```python
set_avatar(_img_path : str | None = None_) → None[source]
```
Tokens:
Raw