:py:mod:`aiosignald` ==================== .. py:module:: aiosignald Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 error/index.rst exc/index.rst generated/index.rst util/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: aiosignald.SignaldAPI .. py:class:: SignaldAPI(on_con_lost: Optional[asyncio.Future] = None) Bases: :py:obj:`aiosignald.util.JSONProtocol` Interface for stream protocol. The user should implement this interface. They can inherit from this class but don't need to. The implementations here do nothing (they don't raise exceptions). When the user wants to requests a transport, they pass a protocol factory to a utility function (e.g., EventLoop.create_connection()). When the connection is made successfully, connection_made() is called with a suitable transport object. Then data_received() will be called 0 or more times with data (bytes) received from the transport; finally, connection_lost() will be called exactly once with either an exception object or None as an argument. State machine of calls: start -> CM [-> DR*] [-> ER?] -> CL -> end * CM: connection_made() * DR: data_received() * ER: eof_received() * CL: connection_lost() .. py:method:: send(username: Optional[str] = None, account: Optional[str] = None, recipientAddress: Optional[JsonAddressv1] = None, recipientGroupId: Optional[str] = None, messageBody: Optional[str] = None, attachments: Optional[list[JsonAttachmentv1]] = None, quote: Optional[JsonQuotev1] = None, timestamp: Optional[int] = None, mentions: Optional[list[JsonMentionv1]] = None, previews: Optional[list[JsonPreviewv1]] = None, members: Optional[list[JsonAddressv1]] = None, is_for_story: Optional[bool] = None) -> SendResponsev1 :async: :param username: Example: "+12024561414" :param account: Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param recipientAddress: :param recipientGroupId: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param messageBody: Example: "hello" :param attachments: :param quote: :param timestamp: :param mentions: :param previews: :param members: Optionally set to a sub-set of group members. Ignored if recipientGroupId isn't specified :param is_for_story: set to true when replying to a story .. py:method:: react(username: Optional[str] = None, recipientAddress: Optional[JsonAddressv1] = None, recipientGroupId: Optional[str] = None, reaction: Optional[JsonReactionv1] = None, timestamp: Optional[int] = None, members: Optional[list[JsonAddressv1]] = None) -> SendResponsev1 :async: react to a previous message :param username: Example: "+12024561414" :param recipientAddress: :param recipientGroupId: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param reaction: :param timestamp: :param members: Optionally set to a sub-set of group members. Ignored if recipientGroupId isn't specified .. py:method:: version() -> JsonVersionMessagev1 :async: .. py:method:: accept_invitation(account: Optional[str] = None, groupID: Optional[str] = None) -> JsonGroupV2Infov1 :async: Accept a v2 group invitation. Note that you must have a profile name set to join groups. :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param groupID: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" .. py:method:: approve_membership(account: Optional[str] = None, groupID: Optional[str] = None, members: Optional[list[JsonAddressv1]] = None) -> JsonGroupV2Infov1 :async: approve a request to join a group :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param groupID: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param members: list of requesting members to approve .. py:method:: get_group(account: Optional[str] = None, groupID: Optional[str] = None, revision: Optional[int] = None) -> JsonGroupV2Infov1 :async: Query the server for the latest state of a known group. If the account is not a member of the group, an UnknownGroupError is returned. :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param groupID: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param revision: the latest known revision, default value (-1) forces fetch from server .. py:method:: get_linked_devices(account: Optional[str] = None) -> LinkedDevicesv1 :async: list all linked devices on a Signal account :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" .. py:method:: join_group(account: Optional[str] = None, uri: Optional[str] = None) -> JsonGroupJoinInfov1 :async: Join a group using the a signal.group URL. Note that you must have a profile name set to join groups. :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param uri: The signal.group URL Example: "https://signal.group/#CjQKINH_GZhXhfifTcnBkaKTNRxW-hHKnGSq-cJNyPVqHRp8EhDUB7zjKNEl0NaULhsqJCX3" .. py:method:: remove_linked_device(account: Optional[str] = None, deviceId: Optional[int] = None) :async: Remove a linked device from the Signal account. Only allowed when the local device id is 1 :param account: The account to interact with Example: "+12024561414" :param deviceId: the ID of the device to unlink Example: 3 .. py:method:: update_group(account: Optional[str] = None, groupID: Optional[str] = None, title: Optional[str] = None, description: Optional[str] = None, avatar: Optional[str] = None, updateTimer: Optional[int] = None, addMembers: Optional[list[JsonAddressv1]] = None, removeMembers: Optional[list[JsonAddressv1]] = None, updateRole: Optional[GroupMemberv1] = None, updateAccessControl: Optional[GroupAccessControlv1] = None, resetLink: Optional[bool] = None, announcements: Optional[str] = None) -> GroupInfov1 :async: modify a group. Note that only one modification action may be performed at once :param account: The identifier of the account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param groupID: the ID of the group to update Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param title: Example: "Parkdale Run Club" :param description: A new group description. Set to empty string to remove an existing description. Example: "A club for running in Parkdale" :param avatar: Example: "/tmp/image.jpg" :param updateTimer: update the group timer. :param addMembers: :param removeMembers: :param updateRole: :param updateAccessControl: note that only one of the access controls may be updated per request :param resetLink: regenerate the group link password, invalidating the old one :param announcements: ENABLED to only allow admins to post messages, DISABLED to allow anyone to post .. py:method:: set_profile(account: Optional[str] = None, name: Optional[str] = None, avatarFile: Optional[str] = None, about: Optional[str] = None, emoji: Optional[str] = None, mobilecoin_address: Optional[str] = None, visible_badge_ids: Optional[list[str]] = None) :async: :param account: The phone number of the account to use Example: "+12024561414" :param name: Change the profile name Example: "signald user" :param avatarFile: Path to new profile avatar file. If unset or null, unset the profile avatar Example: "/tmp/image.jpg" :param about: Change the 'about' profile field :param emoji: Change the profile emoji :param mobilecoin_address: Change the profile payment address. Payment address must be a *base64-encoded* MobileCoin address. Note that this is not the traditional MobileCoin address encoding, which is custom. Clients are responsible for converting between MobileCoin's custom base58 on the user-facing side and base64 encoding on the signald side. :param visible_badge_ids: configure visible badge IDs .. py:method:: resolve_address(account: Optional[str] = None, partial: Optional[JsonAddressv1] = None) -> JsonAddressv1 :async: Resolve a partial JsonAddress with only a number or UUID to one with both. Anywhere that signald accepts a JsonAddress will except a partial, this is a convenience function for client authors, mostly because signald doesn't resolve all the partials it returns. :param account: The signal account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param partial: The partial address, missing fields .. py:method:: mark_read(account: Optional[str] = None, to: Optional[JsonAddressv1] = None, timestamps: Optional[list[int]] = None, when: Optional[int] = None) :async: :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param to: The address that sent the message being marked as read :param timestamps: List of messages to mark as read Example: 1615576442475 :param when: .. py:method:: get_profile(account: Optional[str] = None, async_: Optional[bool] = None, address: Optional[JsonAddressv1] = None) -> Profilev1 :async: Get all information available about a user :param account: the signald account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param async_: if true, return results from local store immediately, refreshing from server in the background if needed. if false (default), block until profile can be retrieved from server :param address: the address to look up .. py:method:: list_groups(account: Optional[str] = None) -> GroupListv1 :async: :param account: Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" .. py:method:: list_contacts(account: Optional[str] = None, async_: Optional[bool] = None) -> ProfileListv1 :async: :param account: Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param async_: return results from local store immediately, refreshing from server afterward if needed. If false (default), block until all pending profiles have been retrieved. .. py:method:: create_group(account: Optional[str] = None, title: Optional[str] = None, avatar: Optional[str] = None, members: Optional[list[JsonAddressv1]] = None, timer: Optional[int] = None, member_role: Optional[str] = None) -> JsonGroupV2Infov1 :async: :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param title: Example: "Parkdale Run Club" :param avatar: Example: "/tmp/image.jpg" :param members: :param timer: the message expiration timer :param member_role: The role of all members other than the group creator. Options are ADMINISTRATOR or DEFAULT (case insensitive) Example: "ADMINISTRATOR" .. py:method:: leave_group(account: Optional[str] = None, groupID: Optional[str] = None) -> GroupInfov1 :async: :param account: The account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param groupID: The group to leave Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" .. py:method:: generate_linking_uri(server: Optional[str] = None) -> LinkingURIv1 :async: Generate a linking URI. Typically this is QR encoded and scanned by the primary device. Submit the returned session_id with a finish_link request. :param server: The identifier of the server to use. Leave blank for default (usually Signal production servers but configurable at build time) .. py:method:: finish_link(overwrite: Optional[bool] = None, device_name: Optional[str] = None, session_id: Optional[str] = None) -> Accountv1 :async: After a linking URI has been requested, finish_link must be called with the session_id provided with the URI. it will return information about the new account once the linking process is completed by the other device and the new account is setup. Note that the account setup process can sometimes take some time, if rapid userfeedback is required after scanning, use wait_for_scan first, then finish setup with finish_link. :param overwrite: overwrite existing account data if the phone number conflicts. false by default :param device_name: :param session_id: .. py:method:: add_device(account: Optional[str] = None, uri: Optional[str] = None) :async: Link a new device to a local Signal account :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param uri: the sgnl://linkdevice uri provided (typically in qr code form) by the new device Example: "sgnl://linkdevice?uuid=jAaZ5lxLfh7zVw5WELd6-Q&pub_key=BfFbjSwmAgpVJBXUdfmSgf61eX3a%2Bq9AoxAVpl1HUap9" .. py:method:: register(account: Optional[str] = None, voice: Optional[bool] = None, captcha: Optional[str] = None, server: Optional[str] = None) -> Accountv1 :async: begin the account registration process by requesting a phone number verification code. when the code is received, submit it with a verify request :param account: the e164 phone number to register with Example: "+12024561414" :param voice: set to true to request a voice call instead of an SMS for verification :param captcha: See https://signald.org/articles/captcha/ :param server: The identifier of the server to use. Leave blank for default (usually Signal production servers but configurable at build time) .. py:method:: verify(account: Optional[str] = None, code: Optional[str] = None) -> Accountv1 :async: verify an account's phone number with a code after registering, completing the account creation process :param account: the e164 phone number being verified Example: "+12024561414" :param code: the verification code, dash (-) optional Example: "555555" .. py:method:: get_identities(account: Optional[str] = None, address: Optional[JsonAddressv1] = None) -> IdentityKeyListv1 :async: Get information about a known keys for a particular address :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param address: address to get keys for .. py:method:: trust(account: Optional[str] = None, address: Optional[JsonAddressv1] = None, safety_number: Optional[str] = None, qr_code_data: Optional[str] = None, trust_level: Optional[str] = None) :async: Trust another user's safety number using either the QR code data or the safety number text :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param address: The user to query identity keys for :param safety_number: required if qr_code_data is absent Example: "373453558586758076680580548714989751943247272727416091564451" :param qr_code_data: base64-encoded QR code data. required if safety_number is absent :param trust_level: One of TRUSTED_UNVERIFIED, TRUSTED_VERIFIED or UNTRUSTED. Default is TRUSTED_VERIFIED Example: "TRUSTED_VERIFIED" .. py:method:: delete_account(account: Optional[str] = None, server: Optional[bool] = None) :async: delete all account data signald has on disk, and optionally delete the account from the server as well. Note that this is not "unlink" and will delete the entire account, even from a linked device. :param account: The account to delete Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param server: delete account information from the server as well (default false) .. py:method:: typing(account: Optional[str] = None, address: Optional[JsonAddressv1] = None, group: Optional[str] = None, typing: Optional[bool] = None, when: Optional[int] = None) :async: send a typing started or stopped message :param account: The account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param address: :param group: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param typing: Example: true :param when: .. py:method:: reset_session(account: Optional[str] = None, address: Optional[JsonAddressv1] = None, timestamp: Optional[int] = None) -> SendResponsev1 :async: reset a session with a particular user :param account: The account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param address: the user to reset session with :param timestamp: .. py:method:: request_sync(groups: Optional[bool] = None, configuration: Optional[bool] = None, contacts: Optional[bool] = None, blocked: Optional[bool] = None, keys: Optional[bool] = None, account: Optional[str] = None) :async: Request other devices on the account send us their group list, syncable config and contact list. :param groups: request group sync (default true) :param configuration: request configuration sync (default true) :param contacts: request contact sync (default true) :param blocked: request block list sync (default true) :param keys: request storage service keys :param account: The account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" .. py:method:: list_accounts() -> AccountListv1 :async: return all local accounts .. py:method:: group_link_info(account: Optional[str] = None, uri: Optional[str] = None) -> JsonGroupJoinInfov1 :async: Get information about a group from a signal.group link :param account: The account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param uri: the signald.group link Example: "https://signal.group/#CjQKINH_GZhXhfifTcnBkaKTNRxW-hHKnGSq-cJNyPVqHRp8EhDUB7zjKNEl0NaULhsqJCX3" .. py:method:: update_contact(account: Optional[str] = None, address: Optional[JsonAddressv1] = None, name: Optional[str] = None, color: Optional[str] = None, inbox_position: Optional[int] = None) -> Profilev1 :async: update information about a local contact :param account: Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param address: :param name: :param color: :param inbox_position: .. py:method:: set_expiration(account: Optional[str] = None, address: Optional[JsonAddressv1] = None, group: Optional[str] = None, expiration: Optional[int] = None) -> SendResponsev1 :async: Set the message expiration timer for a thread. Expiration must be specified in seconds, set to 0 to disable timer :param account: The account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param address: :param group: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param expiration: Example: 604800 .. py:method:: set_device_name(account: Optional[str] = None, device_name: Optional[str] = None) :async: set this device's name. This will show up on the mobile device on the same account under settings -> linked devices :param account: The account to set the device name of Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param device_name: The device name .. py:method:: get_all_identities(account: Optional[str] = None) -> AllIdentityKeyListv1 :async: get all known identity keys :param account: The account to interact with Example: "+12024561414" .. py:method:: subscribe(account: Optional[str] = None) :async: receive incoming messages. After making a subscribe request, incoming messages will be sent to the client encoded as ClientMessageWrapper. Send an unsubscribe request or disconnect from the socket to stop receiving messages. :param account: The account to subscribe to incoming message for Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" .. py:method:: unsubscribe(account: Optional[str] = None) :async: See subscribe for more info :param account: The account to unsubscribe from Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" .. py:method:: remote_delete(account: Optional[str] = None, address: Optional[JsonAddressv1] = None, group: Optional[str] = None, timestamp: Optional[int] = None, members: Optional[list[JsonAddressv1]] = None) -> SendResponsev1 :async: delete a message previously sent :param account: the account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param address: the address to send the delete message to. should match address the message to be deleted was sent to. required if group is not set. :param group: the group to send the delete message to. should match group the message to be deleted was sent to. required if address is not set. Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param timestamp: :param members: Optionally set to a sub-set of group members. Ignored if group isn't specified .. py:method:: add_server(server: Optional[Serverv1] = None) -> Stringv1 :async: add a new server to connect to. Returns the new server's UUID. :param server: .. py:method:: get_servers() -> ServerListv1 :async: .. py:method:: delete_server(uuid: Optional[str] = None) :async: :param uuid: .. py:method:: send_payment(account: Optional[str] = None, address: Optional[JsonAddressv1] = None, payment: Optional[Paymentv1] = None, when: Optional[int] = None) -> SendResponsev1 :async: send a mobilecoin payment :param account: the account to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param address: the address to send the payment message to :param payment: :param when: .. py:method:: get_remote_config(account: Optional[str] = None) -> RemoteConfigListv1 :async: Retrieves the remote config (feature flags) from the server. :param account: The account to use to retrieve the remote config Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" .. py:method:: refuse_membership(account: Optional[str] = None, members: Optional[list[JsonAddressv1]] = None, group_id: Optional[str] = None, also_ban: Optional[bool] = None) -> JsonGroupV2Infov1 :async: deny a request to join a group :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param members: list of requesting members to refuse :param group_id: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param also_ban: .. py:method:: submit_challenge(account: Optional[str] = None, challenge: Optional[str] = None, captcha_token: Optional[str] = None) :async: :param account: Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param challenge: :param captcha_token: .. py:method:: is_identifier_registered(account: Optional[str] = None, identifier: Optional[str] = None) -> BooleanMessagev1 :async: Determine whether an account identifier is registered on the Signal service. :param account: The account to use to use Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param identifier: The UUID of an identifier to check if it is registered on Signal. This UUID is either a Phone Number Identity (PNI) or an Account Identity (ACI). Example: "aeed01f0-a234-478e-8cf7-261c283151e7" .. py:method:: wait_for_scan(session_id: Optional[str] = None) :async: An optional part of the linking process. Intended to be called after displaying the QR code, will return quickly after the user scans the QR code. finish_link must be called after wait_for_scan returns a non-error :param session_id: .. py:method:: get_group_revision_pages(account: Optional[str] = None, group_id: Optional[str] = None, from_revision: Optional[int] = None, include_first_revision: Optional[bool] = None) -> GroupHistoryPagev1 :async: Query the server for group revision history. The history contains information about the changes between each revision and the user that made the change. :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param group_id: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param from_revision: The revision to start the pages from. Note that if this is lower than the revision you joined the group, an AuthorizationFailedError is returned. :param include_first_revision: Whether to include the first state in the returned pages (default false) .. py:method:: send_sync_message(account: Optional[str] = None, view_once_open_message: Optional[JsonViewOnceOpenMessagev1] = None, message_request_response: Optional[JsonMessageRequestResponseMessagev1] = None) -> JsonSendMessageResultv1 :async: Sends a sync message to the account's devices :param account: Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param view_once_open_message: This can be set to indicate to other devices about having viewed a view-once message. :param message_request_response: This can be set to indicate to other devices about a response to an incoming message request from an unknown user or group. Warning: Using the BLOCK and BLOCK_AND_DELETE options relies on other devices to do the blocking, and it does not make you leave the group! .. py:method:: ban_user(account: Optional[str] = None, group_id: Optional[str] = None, users: Optional[list[JsonAddressv1]] = None) -> JsonGroupV2Infov1 :async: Bans users from a group. This works even if the users aren't in the group. If they are currently in the group, they will also be removed. :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param group_id: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param users: List of users to ban .. py:method:: unban_user(account: Optional[str] = None, group_id: Optional[str] = None, users: Optional[list[JsonAddressv1]] = None) -> JsonGroupV2Infov1 :async: Unbans users from a group. :param account: The account to interact with Example: "0cc10e61-d64c-4dbc-b51c-334f7dd45a4a" :param group_id: Example: "EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=" :param users: List of users to unban .. py:exception:: SignaldException(payload: dict[str, str]) Bases: :py:obj:`Exception` Base class to translate signald's response payloads into python exceptions .. py:method:: __str__() Return str(self).