aiosignald

Submodules

Package Contents

Classes

SignaldAPI

Interface for stream protocol.
class aiosignald.SignaldAPI(on_con_lost: asyncio.Future | None = None)

Bases: 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()

async send(username: str | None = None, account: str | None = None, recipientAddress: JsonAddressv1 | None = None, recipientGroupId: str | None = None, messageBody: str | None = None, attachments: list[JsonAttachmentv1] | None = None, quote: JsonQuotev1 | None = None, timestamp: int | None = None, mentions: list[JsonMentionv1] | None = None, previews: list[JsonPreviewv1] | None = None, members: list[JsonAddressv1] | None = None, is_for_story: bool | None = None) → SendResponsev1
Parameters:

  • username – Example: “+12024561414”

  • account – Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • recipientAddress –

  • recipientGroupId – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • messageBody – Example: “hello”

  • attachments –

  • quote –

  • timestamp –

  • mentions –

  • previews –

  • members – Optionally set to a sub-set of group members. Ignored if recipientGroupId isn’t specified

  • is_for_story – set to true when replying to a story

async react(username: str | None = None, recipientAddress: JsonAddressv1 | None = None, recipientGroupId: str | None = None, reaction: JsonReactionv1 | None = None, timestamp: int | None = None, members: list[JsonAddressv1] | None = None) → SendResponsev1

react to a previous message

Parameters:

  • username – Example: “+12024561414”

  • recipientAddress –

  • recipientGroupId – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • reaction –

  • timestamp –

  • members – Optionally set to a sub-set of group members. Ignored if recipientGroupId isn’t specified

async version() → JsonVersionMessagev1
async accept_invitation(account: str | None = None, groupID: str | None = None) → JsonGroupV2Infov1

Accept a v2 group invitation. Note that you must have a profile name set to join groups.

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • groupID – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

async approve_membership(account: str | None = None, groupID: str | None = None, members: list[JsonAddressv1] | None = None) → JsonGroupV2Infov1

approve a request to join a group

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • groupID – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • members – list of requesting members to approve

async get_group(account: str | None = None, groupID: str | None = None, revision: int | None = None) → JsonGroupV2Infov1

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.

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • groupID – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • revision – the latest known revision, default value (-1) forces fetch from server

async get_linked_devices(account: str | None = None) → LinkedDevicesv1

list all linked devices on a Signal account

Parameters:

account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

async join_group(account: str | None = None, uri: str | None = None) → JsonGroupJoinInfov1

Join a group using the a signal.group URL. Note that you must have a profile name set to join groups.

Parameters:
async remove_linked_device(account: str | None = None, deviceId: int | None = None)

Remove a linked device from the Signal account. Only allowed when the local device id is 1

Parameters:

  • account – The account to interact with Example: “+12024561414”

  • deviceId – the ID of the device to unlink Example: 3

async update_group(account: str | None = None, groupID: str | None = None, title: str | None = None, description: str | None = None, avatar: str | None = None, updateTimer: int | None = None, addMembers: list[JsonAddressv1] | None = None, removeMembers: list[JsonAddressv1] | None = None, updateRole: GroupMemberv1 | None = None, updateAccessControl: GroupAccessControlv1 | None = None, resetLink: bool | None = None, announcements: str | None = None) → GroupInfov1

modify a group. Note that only one modification action may be performed at once

Parameters:

  • account – The identifier of the account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • groupID – the ID of the group to update Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • title – Example: “Parkdale Run Club”

  • description – A new group description. Set to empty string to remove an existing description. Example: “A club for running in Parkdale”

  • avatar – Example: “/tmp/image.jpg”

  • updateTimer – update the group timer.

  • addMembers –

  • removeMembers –

  • updateRole –

  • updateAccessControl – note that only one of the access controls may be updated per request

  • resetLink – regenerate the group link password, invalidating the old one

  • announcements – ENABLED to only allow admins to post messages, DISABLED to allow anyone to post

async set_profile(account: str | None = None, name: str | None = None, avatarFile: str | None = None, about: str | None = None, emoji: str | None = None, mobilecoin_address: str | None = None, visible_badge_ids: list[str] | None = None)
Parameters:

  • account – The phone number of the account to use Example: “+12024561414”

  • name – Change the profile name Example: “signald user”

  • avatarFile – Path to new profile avatar file. If unset or null, unset the profile avatar Example: “/tmp/image.jpg”

  • about – Change the ‘about’ profile field

  • emoji – Change the profile emoji

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

  • visible_badge_ids – configure visible badge IDs

async resolve_address(account: str | None = None, partial: JsonAddressv1 | None = None) → JsonAddressv1

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.

Parameters:

  • account – The signal account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • partial – The partial address, missing fields

async mark_read(account: str | None = None, to: JsonAddressv1 | None = None, timestamps: list[int] | None = None, when: int | None = None)
Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • to – The address that sent the message being marked as read

  • timestamps – List of messages to mark as read Example: 1615576442475

  • when –

async get_profile(account: str | None = None, async_: bool | None = None, address: JsonAddressv1 | None = None) → Profilev1

Get all information available about a user

Parameters:

  • account – the signald account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • 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

  • address – the address to look up

async list_groups(account: str | None = None) → GroupListv1
Parameters:

account – Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

async list_contacts(account: str | None = None, async_: bool | None = None) → ProfileListv1
Parameters:

  • account – Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • async – return results from local store immediately, refreshing from server afterward if needed. If false (default), block until all pending profiles have been retrieved.

async create_group(account: str | None = None, title: str | None = None, avatar: str | None = None, members: list[JsonAddressv1] | None = None, timer: int | None = None, member_role: str | None = None) → JsonGroupV2Infov1
Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • title – Example: “Parkdale Run Club”

  • avatar – Example: “/tmp/image.jpg”

  • members –

  • timer – the message expiration timer

  • member_role – The role of all members other than the group creator. Options are ADMINISTRATOR or DEFAULT (case insensitive) Example: “ADMINISTRATOR”

async leave_group(account: str | None = None, groupID: str | None = None) → GroupInfov1
Parameters:

  • account – The account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • groupID – The group to leave Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

async generate_linking_uri(server: str | None = None) → LinkingURIv1

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.

Parameters:

server – The identifier of the server to use. Leave blank for default (usually Signal production servers but configurable at build time)

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.

Parameters:

  • overwrite – overwrite existing account data if the phone number conflicts. false by default

  • device_name –

  • session_id –

async add_device(account: str | None = None, uri: str | None = None)

Link a new device to a local Signal account

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • 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”

async register(account: str | None = None, voice: bool | None = None, captcha: str | None = None, server: str | None = None) → Accountv1

begin the account registration process by requesting a phone number verification code. when the code is received, submit it with a verify request

Parameters:

  • account – the e164 phone number to register with Example: “+12024561414”

  • voice – set to true to request a voice call instead of an SMS for verification

  • captcha – See https://signald.org/articles/captcha/

  • server – The identifier of the server to use. Leave blank for default (usually Signal production servers but configurable at build time)

async verify(account: str | None = None, code: str | None = None) → Accountv1

verify an account’s phone number with a code after registering, completing the account creation process

Parameters:

  • account – the e164 phone number being verified Example: “+12024561414”

  • code – the verification code, dash (-) optional Example: “555555”

async get_identities(account: str | None = None, address: JsonAddressv1 | None = None) → IdentityKeyListv1

Get information about a known keys for a particular address

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • address – address to get keys for

async trust(account: str | None = None, address: JsonAddressv1 | None = None, safety_number: str | None = None, qr_code_data: str | None = None, trust_level: str | None = None)

Trust another user’s safety number using either the QR code data or the safety number text

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • address – The user to query identity keys for

  • safety_number – required if qr_code_data is absent Example: “373453558586758076680580548714989751943247272727416091564451”

  • qr_code_data – base64-encoded QR code data. required if safety_number is absent

  • trust_level – One of TRUSTED_UNVERIFIED, TRUSTED_VERIFIED or UNTRUSTED. Default is TRUSTED_VERIFIED Example: “TRUSTED_VERIFIED”

async delete_account(account: str | None = None, server: bool | None = None)

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.

Parameters:

  • account – The account to delete Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • server – delete account information from the server as well (default false)

async typing(account: str | None = None, address: JsonAddressv1 | None = None, group: str | None = None, typing: bool | None = None, when: int | None = None)

send a typing started or stopped message

Parameters:

  • account – The account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • address –

  • group – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • typing – Example: true

  • when –

async reset_session(account: str | None = None, address: JsonAddressv1 | None = None, timestamp: int | None = None) → SendResponsev1

reset a session with a particular user

Parameters:

  • account – The account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • address – the user to reset session with

  • timestamp –

async request_sync(groups: bool | None = None, configuration: bool | None = None, contacts: bool | None = None, blocked: bool | None = None, keys: bool | None = None, account: str | None = None)

Request other devices on the account send us their group list, syncable config and contact list.

Parameters:

  • groups – request group sync (default true)

  • configuration – request configuration sync (default true)

  • contacts – request contact sync (default true)

  • blocked – request block list sync (default true)

  • keys – request storage service keys

  • account – The account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

async list_accounts() → AccountListv1

return all local accounts

Get information about a group from a signal.group link

Parameters:
async update_contact(account: str | None = None, address: JsonAddressv1 | None = None, name: str | None = None, color: str | None = None, inbox_position: int | None = None) → Profilev1

update information about a local contact

Parameters:

  • account – Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • address –

  • name –

  • color –

  • inbox_position –

async set_expiration(account: str | None = None, address: JsonAddressv1 | None = None, group: str | None = None, expiration: int | None = None) → SendResponsev1

Set the message expiration timer for a thread. Expiration must be specified in seconds, set to 0 to disable timer

Parameters:

  • account – The account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • address –

  • group – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • expiration – Example: 604800

async set_device_name(account: str | None = None, device_name: str | None = None)

set this device’s name. This will show up on the mobile device on the same account under settings -> linked devices

Parameters:

  • account – The account to set the device name of Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • device_name – The device name

async get_all_identities(account: str | None = None) → AllIdentityKeyListv1

get all known identity keys

Parameters:

account – The account to interact with Example: “+12024561414”

async subscribe(account: str | None = None)

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.

Parameters:

account – The account to subscribe to incoming message for Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

async unsubscribe(account: str | None = None)

See subscribe for more info

Parameters:

account – The account to unsubscribe from Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

async remote_delete(account: str | None = None, address: JsonAddressv1 | None = None, group: str | None = None, timestamp: int | None = None, members: list[JsonAddressv1] | None = None) → SendResponsev1

delete a message previously sent

Parameters:

  • account – the account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

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

  • 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=”

  • timestamp –

  • members – Optionally set to a sub-set of group members. Ignored if group isn’t specified

async add_server(server: Serverv1 | None = None) → Stringv1

add a new server to connect to. Returns the new server’s UUID.

Parameters:

server –

async get_servers() → ServerListv1
async delete_server(uuid: str | None = None)
Parameters:

uuid –

async send_payment(account: str | None = None, address: JsonAddressv1 | None = None, payment: Paymentv1 | None = None, when: int | None = None) → SendResponsev1

send a mobilecoin payment

Parameters:

  • account – the account to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • address – the address to send the payment message to

  • payment –

  • when –

async get_remote_config(account: str | None = None) → RemoteConfigListv1

Retrieves the remote config (feature flags) from the server.

Parameters:

account – The account to use to retrieve the remote config Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

async refuse_membership(account: str | None = None, members: list[JsonAddressv1] | None = None, group_id: str | None = None, also_ban: bool | None = None) → JsonGroupV2Infov1

deny a request to join a group

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • members – list of requesting members to refuse

  • group_id – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • also_ban –

async submit_challenge(account: str | None = None, challenge: str | None = None, captcha_token: str | None = None)
Parameters:

  • account – Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • challenge –

  • captcha_token –

async is_identifier_registered(account: str | None = None, identifier: str | None = None) → BooleanMessagev1

Determine whether an account identifier is registered on the Signal service.

Parameters:

  • account – The account to use to use Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • 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”

async wait_for_scan(session_id: str | None = None)

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

Parameters:

session_id –

async get_group_revision_pages(account: str | None = None, group_id: str | None = None, from_revision: int | None = None, include_first_revision: bool | None = None) → GroupHistoryPagev1

Query the server for group revision history. The history contains information about the changes between each revision and the user that made the change.

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • group_id – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

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

  • include_first_revision – Whether to include the first state in the returned pages (default false)

async send_sync_message(account: str | None = None, view_once_open_message: JsonViewOnceOpenMessagev1 | None = None, message_request_response: JsonMessageRequestResponseMessagev1 | None = None) → JsonSendMessageResultv1

Sends a sync message to the account’s devices

Parameters:

  • account – Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • view_once_open_message – This can be set to indicate to other devices about having viewed a view-once message.

  • 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!

async ban_user(account: str | None = None, group_id: str | None = None, users: list[JsonAddressv1] | None = None) → JsonGroupV2Infov1

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.

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • group_id – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • users – List of users to ban

async unban_user(account: str | None = None, group_id: str | None = None, users: list[JsonAddressv1] | None = None) → JsonGroupV2Infov1

Unbans users from a group.

Parameters:

  • account – The account to interact with Example: “0cc10e61-d64c-4dbc-b51c-334f7dd45a4a”

  • group_id – Example: “EdSqI90cS0UomDpgUXOlCoObWvQOXlH5G3Z2d3f4ayE=”

  • users – List of users to unban

exception aiosignald.SignaldException(payload: dict[str, str])

Bases: Exception

Base class to translate signald’s response payloads into python exceptions

__str__()

Return str(self).