Private _transportAdd a member to a group.
If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.
If the group has group protection enabled, only verified contacts can be added to the group.
Sends out #DC_EVENT_CHAT_MODIFIED and #DC_EVENT_MSGS_CHANGED if a status message was sent.
Add a message to the device-chat. Device-messages usually contain update information and some hints that are added during the program runs, multi-device etc. The device-message may be defined by a label; if a message with the same label was added or skipped before, the message is not added again, even if the message was deleted in between. If needed, the device-chat is created before.
Sends the MsgsChanged event on success.
Setting msg to None will prevent the device message with this label from being added in the future.
Create a new broadcast list.
Broadcast lists are similar to groups on the sending device, however, recipients get the messages in a read-only chat and will see who the other members are.
For historical reasons, this function does not take a name directly, instead you have to set the name using dc_set_chat_name() after creating the broadcast list.
Create a new group chat.
After creation, the group has one member with the ID DC_CONTACT_ID_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 BasicChat or FullChat.
This may be useful if you want to show some help for just created groups.
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.
Delete a chat.
Messages are deleted from the device and the chat database entry is deleted. After that, the event #DC_EVENT_MSGS_CHANGED is posted.
Things that are not done implicitly:
To leave a chat explicitly, use leave_group()
Asks the core to start downloading a message fully.
This function is typically called when the user hits the "Download" button
that is shown by the UI in case download_state is 'Available' or 'Failure'
On success, the
DC_MSG "view type of the message" may change or the message may be replaced completely by one or more messages with other message IDs. That may happen e.g. in cases where the message was encrypted and the type could not be determined without fully downloading. Downloaded content can be accessed as usual after download.
To reflect these changes a
DC_EVENT_MSGS_CHANGED event will be emitted.
Estimate the number of messages that will be deleted
by the set_config()-options delete_device_after or delete_server_after.
This is typically used to show the estimated impact to the user
before actually enabling deletion of old messages.
Forward messages to another chat.
All types of messages can be forwarded, however, they will be flagged as such (dc_msg_is_forwarded() is set).
Original sender, info-state and webxdc updates are not forwarded on purpose.
Gets a backup from a remote provider.
This retrieves the backup from a remote device over the network and imports it into the current device.
Can be cancelled by stopping the ongoing process.
Do not forget to call start_io on the account after a successful import, otherwise it will not connect to the email server.
Returns the text of the QR code for the running [CommandApi::provide_backup].
This QR code text can be used in [CommandApi::get_backup] on a second device to
retrieve the backup and setup this second device.
This call will block until the QR code is ready,
even if there is no concurrent call to [CommandApi::provide_backup],
but will fail after 60 seconds to avoid deadlocks.
Returns the rendered QR code for the running [CommandApi::provide_backup].
This QR code can be used in [CommandApi::get_backup] on a second device to
retrieve the backup and setup this second device.
This call will block until the QR code is ready,
even if there is no concurrent call to [CommandApi::provide_backup],
but will fail after 60 seconds to avoid deadlocks.
Returns the QR code rendered as an SVG image.
Get the contact IDs belonging to a chat.
for normal chats, the function always returns exactly one contact, DC_CONTACT_ID_SELF is returned only for SELF-chats.
for group chats all members are returned, DC_CONTACT_ID_SELF is returned explicitly as it may happen that oneself gets removed from a still existing group
for broadcasts, all recipients are returned, DC_CONTACT_ID_SELF is not included
for mailing lists, the behavior is not documented currently, we will decide on that later. for now, the UI should not show the list for mailing lists. (we do not know all members and there is not always a global mailing list address, so we could return only SELF or the known members; this is not decided yet)
Get encryption info for a chat. Get a multi-line encryption info, containing encryption preferences of all members. Can be used to find out why messages sent to group are not encrypted.
returns Multi-line text
Returns all message IDs of the given types in a chat. Typically used to show a gallery.
The list is already sorted and starts with the oldest message. Clients should not try to re-sort the list as this would be an expensive action and would result in inconsistencies between clients.
Setting chat_id to None (null in typescript) means get messages with media
from any chat of the currently used account.
Get QR code text that will offer a SecureJoin invitation.
If chat_id is a group chat ID, SecureJoin QR code for the group is returned.
If chat_id is unset, setup contact QR code is returned.
Get QR code (text and SVG) that will offer a Setup-Contact or Verified-Group invitation. The QR code is compatible to the OPENPGP4FPR format so that a basic fingerprint comparison also works e.g. with OpenKeychain.
The scanning device will pass the scanned content to checkQr() then;
if checkQr() returns askVerifyContact or askVerifyGroup
an out-of-band-verification can be joined using secure_join()
chat_id: If set to a group-chat-id, the Verified-Group-Invite protocol is offered in the QR code; works for protected groups as well as for normal groups. If not set, the Setup-Contact protocol is offered in the QR code. See https://securejoin.delta.chat/ for details about both protocols.
return format: [code, svg]
Get the current connectivity, i.e. whether the device is connected to the IMAP server. One of:
We don't use exact values but ranges here so that we can split up states into multiple states in the future.
Meant as a rough overview that can be shown e.g. in the title of the main screen.
If the connectivity changes, a #DC_EVENT_CONNECTIVITY_CHANGED will be emitted.
Get an overview of the current connectivity, and possibly more statistics. Meant to give the user more insight about the current status than the basic connectivity info returned by get_connectivity(); show this e.g., if the user taps on said basic connectivity info.
If this page changes, a #DC_EVENT_CONNECTIVITY_CHANGED will be emitted.
This comes as an HTML from the core so that we can easily improve it and the improvement instantly reaches all UIs.
Get encryption info for a contact. Get a multi-line encryption info, containing your fingerprint and the fingerprint of the contact, used e.g. to compare the fingerprints for a simple out-of-band verification.
Get the number of fresh messages in a chat. Typically used to implement a badge with a number in the chatlist.
If the specified chat is muted, the UI should show the badge counter "less obtrusive", e.g. using "gray" instead of "red" color.
Returns the message IDs of all fresh messages of any chat. Typically used for implementing notification summaries or badge counters e.g. on the app icon. The list is already sorted and starts with the most recent fresh message.
Messages belonging to muted chats or to the contact requests are not returned; these messages should not be notified and also badge counters should not include these messages.
To get the number of fresh messages for a single chat, muted or not,
use get_fresh_msg_cnt().
Makes an HTTP GET request and returns a response.
url is the HTTP or HTTPS URL.
Get an informational text for a single message. The text is multiline and may contain e.g. the raw text of the message.
The max. text returned is typically longer (about 100000 characters) than the max. text returned by dc_msg_get_text() (about 30000 characters).
Returns additional information for single message.
Fetch info desktop needs for creating a notification for a message
Returns contacts that sent read receipts and the time of reading.
get multiple messages in one call, if loading one message fails the error is stored in the result object in it's place.
this is the batch variant of [get_message]
Search next/previous message based on a given message and a list of types. Typically used to implement the "next" and "previous" buttons in a gallery or in a media player.
one combined call for getting chat::get_next_media for both directions the manual chat::get_next_media in only one direction is not exposed by the jsonrpc yet
Deprecated 2023-10-03, use get_chat_media method
and navigate the returned array instead.
Gets messages to be processed by the bot and returns their IDs.
Only messages with database ID higher than last_msg_id config value
are returned. After processing the messages, the bot should
update last_msg_id by calling markseen_msgs
or manually updating the value to avoid getting already
processed messages.
Returns provider for the given domain.
This function looks up domain in offline database.
For compatibility, email address can be passed to this function instead of the domain.
Get info from a webxdc message
Returns Webxdc instance used for optional integrations.
UI can open the Webxdc as usual.
Returns None if there is no integration; the caller can add one using set_webxdc_integration then.
integrate_for is the chat to get the integration for.
Check whether the chat is currently muted (can be changed by set_chat_mute_duration()).
This is available as a standalone function outside of fullchat, because it might be only needed for notification
Check if an e-mail address belongs to a known and unblocked contact. To get a list of all known and unblocked contacts, use contacts_get_contacts().
To validate an e-mail address independently of the contact database use check_email_validity().
Mark all messages in a chat as noticed. Noticed messages are no longer fresh and do not count as being unseen but are still waiting for being marked as "seen" using markseen_msgs() (IMAP/MDNs is not done for noticed messages).
Calling this function usually results in the event #DC_EVENT_MSGS_NOTICED. See also markseen_msgs().
Mark messages as presented to the user. Typically, UIs call this function on scrolling through the message list, when the messages are presented at least for a little moment. The concrete action depends on the type of the chat and on the users settings (dc_msgs_presented() may be a better name therefore, but well. :)
mdns_enabled is set)
and the internal state is changed toDC_STATE_IN_SEEN to reflect these actions.
Moreover, timer is started for incoming ephemeral messages. This also happens for contact requests chats.
This function updates last_msg_id configuration value
to the maximum of the current value and IDs passed to this function.
Bots which mark messages as seen can rely on this side effect
to avoid updating last_msg_id value manually.
One #DC_EVENT_MSGS_NOTICED event is emitted per modified chat.
Parses a vCard file located at the given path. Returns contacts in their original order.
Offers a backup for remote devices to retrieve.
Can be cancelled by stopping the ongoing process. Success or failure can be tracked
via the ImexProgress event which should either reach 1000 for success or 0 for
failure.
This stops IO while it is running.
Returns once a remote device has retrieved the backup, or is cancelled.
Remove a member from a group.
If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.
Sends out #DC_EVENT_CHAT_MODIFIED and #DC_EVENT_MSGS_CHANGED if a status message was sent.
Resend messages and make information available for newly added chat members. Resending sends out the original message, however, recipients and webxdc-status may differ. Clients that already have the original message can still ignore the resent message as they have tracked the state by dedicated updates.
Some messages cannot be resent, eg. info-messages, drafts, already pending messages or messages that are not sent by SELF.
message_ids all message IDs that should be resend. All messages must belong to the same chat.
Search messages containing the given query string. Searching can be done globally (chat_id=None) or in a specified chat only (chat_id set).
Global search results are typically displayed using dc_msg_get_summary(), chat search results may just highlight the corresponding messages and present a prev/next button.
For the global search, the result is limited to 1000 messages, this allows an incremental search done fast. So, when getting exactly 1000 messages, the result actually may be truncated; the UIs may display sth. like "1000+ messages found" in this case. The chat search (if chat_id is set) is not limited.
Continue a Setup-Contact or Verified-Group-Invite protocol
started on another device with get_chat_securejoin_qr_code_svg().
This function is typically called when check_qr() returns
type=AskVerifyContact or type=AskVerifyGroup.
The function returns immediately and the handshake runs in background, sending and receiving several messages. During the handshake, info messages are added to the chat, showing progress, success or errors.
Subsequent calls of secure_join() will abort previous, unfinished handshakes.
See https://securejoin.delta.chat/ for details about both protocols.
qr: The text of the scanned QR code. Typically, the same string as given
to check_qr().
returns: The chat ID of the joined chat, the UI may redirect to the this chat. A returned chat ID does not guarantee that the chat is protected or the belonging contact is verified.
Send a reaction to message.
Reaction is a string of emojis separated by spaces. Reaction to a single message can be sent multiple times. The last reaction received overrides all previously received reactions. It is possible to remove all reactions by sending an empty string.
Set mute duration of a chat.
The UI can then call is_chat_muted() when receiving a new message to decide whether it should trigger an notification.
Muted chats should not sound or vibrate and should not show a visual notification in the system area. Moreover, muted chats should be excluded from global badge counter (get_fresh_msgs() skips muted chats therefore) and the in-app, per-chat badge counter should use a less obtrusive color.
Sends out #DC_EVENT_CHAT_MODIFIED.
Set group name.
If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.
Sends out #DC_EVENT_CHAT_MODIFIED and #DC_EVENT_MSGS_CHANGED if a status message was sent.
Set group profile image.
If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function.
Sends out #DC_EVENT_CHAT_MODIFIED and #DC_EVENT_MSGS_CHANGED if a status message was sent.
To find out the profile image of a chat, use dc_chat_get_profile_image()
Set configuration values from a QR code. (technically from the URI that is stored in the qrcode)
Before this function is called, checkQr() should confirm the type of the
QR code is account or webrtcInstance.
Internally, the function will call dc_set_config() with the appropriate keys,
Waits for messages to be processed by the bot and returns their IDs.
This function is similar to get_next_msgs,
but waits for internal new message notification before returning.
New message notification is sent when new message is added to the database,
on initialization, when I/O is started and when I/O is stopped.
This allows bots to use wait_next_msgs in a loop to process
old messages after initialization and during the bot runtime.
To shutdown the bot, stopping I/O can be used to interrupt
pending or next wait_next_msgs call.
Generated using TypeDoc
Performs a background fetch for all accounts in parallel with a timeout.
The
AccountsBackgroundFetchDoneevent is emitted at the end even in case of timeout. Process all events until you get this one and you can safely return to the background without forgetting to create notifications caused by timing race conditions.