X-Git-Url: https://git.nmode.ca/signal-cli/blobdiff_plain/3c40b11b8a6a0619e92de6d54262966aee27fd5d..94b3d9e2ed91b002751df0e04adba3cbc79e6bd1:/man/signal-cli-dbus.5.adoc?ds=sidebyside diff --git a/man/signal-cli-dbus.5.adoc b/man/signal-cli-dbus.5.adoc index 508a7881..e379dcfb 100755 --- a/man/signal-cli-dbus.5.adoc +++ b/man/signal-cli-dbus.5.adoc @@ -29,7 +29,7 @@ method(arg1, arg2, ...) -> return Where is according to DBus specification: -* : Array of ... (comma-separated list, array:) +* : Array of ... (comma-separated list) (array:) * (...) : Struct (cannot be sent via `dbus-send`) * : Boolean (false|true) (boolean:) * : Signed 32-bit (int) integer (int32:) @@ -48,9 +48,9 @@ Phone numbers always have the format + == Methods === Control methods -These methods are available if the daemon is started anonymously (without an explicit `-u USERNAME`). -Requests are sent to `/org/asamk/Signal`; requests related to individual accounts are sent to -`/org/asamk/Signal/_441234567890` where the + dialing code is replaced by an underscore (_). +These methods are available if the daemon is started anonymously (without an explicit `-u USERNAME`). +Requests are sent to `/org/asamk/Signal`; requests related to individual accounts are sent to +`/org/asamk/Signal/_441234567890` where the + dialing code is replaced by an underscore (_). Only `version()` is activated in single-user mode; the rest are disabled. link() -> deviceLinkUri:: @@ -58,12 +58,12 @@ link(newDeviceName) -> deviceLinkUri:: * newDeviceName : Name to give new device (defaults to "cli" if no name is given) * deviceLinkUri : URI of newly linked device -Returns a URI of the form "tsdevice:/?uuid=...". This can be piped to a QR encoder to create a display that +Returns a URI of the form "sgnl://linkdevice/?uuid=...". This can be piped to a QR encoder to create a display that can be captured by a Signal smartphone client. For example: `dbus-send --session --dest=org.asamk.Signal --type=method_call --print-reply /org/asamk/Signal org.asamk.Signal.link string:"My secondary client"|tr '\n' '\0'|sed 's/.*string //g'|sed 's/\"//g'|qrencode -s10 -tANSI256` -Exception: Failure +Exceptions: Failure listAccounts() -> accountList:: * accountList : Array of all attached accounts in DBus object path form @@ -89,94 +89,243 @@ verify(number, verificationCode) -> <>:: Command fails if PIN was set after previous registration; use verifyWithPin instead. -Exception: Failure, InvalidNumber +Exceptions: Failure, InvalidNumber verifyWithPin(number, verificationCode, pin) -> <>:: * number : Phone number * verificationCode : Code received from Signal after successful registration request * pin : PIN you set with setPin command after verifying previous registration -Exception: Failure, InvalidNumber +Exceptions: Failure, InvalidNumber version() -> version:: * version : Version string of signal-cli Exceptions: None -=== Other methods +=== Group control methods +The following methods listen to the recipient's object path, which is constructed as follows: +"/org/asamk/Signal/" + DBusNumber +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) -updateGroup(groupId, newName, members, avatar) -> groupId:: -* groupId : Byte array representing the internal group identifier -* newName : New name of group (empty if unchanged) -* members : String array of new members to be invited to group -* avatar : Filename of avatar picture to be set for group (empty if none) +createGroup(groupName, members, avatar) -> groupId:: +* groupName : String representing the display name of the group +* members : String array of new members to be invited to group +* avatar : Filename of avatar picture to be set for group (empty if none) +* groupId : Byte array representing the internal group identifier -Exceptions: AttachmentInvalid, Failure, InvalidNumber, GroupNotFound +Exceptions: AttachmentInvalid, Failure, InvalidNumber; -updateProfile(name, about, aboutEmoji , avatar, remove) -> <>:: -updateProfile(givenName, familyName, about, aboutEmoji , avatar, remove) -> <>:: -* name : Name for your own profile (empty if unchanged) -* givenName : Given name for your own profile (empty if unchanged) -* familyName : Family name for your own profile (empty if unchanged) -* about : About message for profile (empty if unchanged) -* aboutEmoji : Emoji for profile (empty if unchanged) -* avatar : Filename of avatar picture for profile (empty if unchanged) -* remove : Set to true if the existing avatar picture should be removed +getGroup(groupId) -> objectPath:: +* groupId : Byte array representing the internal group identifier +* objectPath : DBusPath for the group + +getGroupMembers(groupId) -> members:: +* groupId : Byte array representing the internal group identifier +* members : String array with the phone numbers of all active members of a group + +Exceptions: None, if the group name is not found an empty array is returned + +joinGroup(inviteURI) -> <>:: +* inviteURI : String starting with https://signal.group/# + +Behavior of this method depends on the `requirePermission` parameter of the `enableLink` method. If permission is required, `joinGroup` adds you to the requesting members list. Permission may be granted based on the group's `PermissionAddMember` property (`ONLY_ADMINS` or `EVERY_MEMBER`). If permission is not required, `joinGroup` admits you immediately to the group. Exceptions: Failure +listGroups() -> groups:: +* groups : Array of Structs(objectPath, groupId, groupName) +** objectPath : DBusPath +** groupId : Byte array representing the internal group identifier +** groupName : String representing the display name of the group -setExpirationTimer(number, expiration) -> <>:: -* number : Phone number of recipient -* expiration : int32 for the number of seconds before messages to this recipient disappear. Set to 0 to disable expiration. +sendGroupMessage(message, attachments, groupId) -> timestamp:: +* message : Text to send (can be UTF8) +* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) +* groupId : Byte array representing the internal group identifier +* timestamp : Long, can be used to identify the corresponding Signal reply + +Exceptions: GroupNotFound, Failure, AttachmentInvalid, InvalidGroupId + +sendGroupMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, groupId) -> timestamp:: +* emoji : Unicode grapheme cluster of the emoji +* remove : Boolean, whether a previously sent reaction (emoji) should be removed +* targetAuthor : String with the phone number of the author of the message to which to react +* targetSentTimestamp : Long representing timestamp of the message to which to react +* groupId : Byte array representing the internal group identifier +* timestamp : Long, can be used to identify the corresponding signal reply + +Exceptions: Failure, InvalidNumber, GroupNotFound, InvalidGroupId + +sendGroupRemoteDeleteMessage(targetSentTimestamp, groupId) -> timestamp:: +* targetSentTimestamp : Long representing timestamp of the message to delete +* groupId : Byte array with base64 encoded group identifier +* timestamp : Long, can be used to identify the corresponding signal reply + +Exceptions: Failure, GroupNotFound, InvalidGroupId + +=== Group methods +The following methods listen to the group's object path, which can be obtained from the listGroups() method and is constructed as follows: +"/org/asamk/Signal/" + DBusNumber + "/Groups/" + DBusGroupId +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) +* DBusGroupId : groupId in base64 format, with underscore (_) replacing plus (+), equals (=), or slash (/) + +Groups have the following (case-sensitive) properties: +* Id (read-only) : Byte array representing the internal group identifier +* Name : Display name of the group +* Description : Description of the group +* Avatar (write-only) : Filename of the avatar +* IsBlocked : true=member will not receive group messages; false=not blocked +* IsMember (read-only) : always true (object path exists only for group members) +* IsAdmin (read-only) : true=member has admin privileges; false=not admin +* MessageExpirationTimer : int32 representing message expiration time for group +* Members (read-only) : String array of group members' phone numbers +* PendingMembers (read-only) : String array of pending members' phone numbers +* RequestingMembers (read-only) : String array of requesting members' phone numbers +* Admins (read-only) : String array of admins' phone numbers +* PermissionAddMember : String representing who has permission to add members +** ONLY_ADMINS, EVERY_MEMBER +* PermissionEditDetails : String representing who may edit group details +** ONLY_ADMINS, EVERY_MEMBER +* PermissionSendMessage : String representing who post messages to group +** ONLY_ADMINS, EVERY_MEMBER (note that ONLY_ADMINS is equivalent to IsAnnouncementGroup) +* GroupInviteLink (read-only) : String of the invitation link (starts with https://signal.group/#) + +To get a property, use (replacing `--session` with `--system` if needed): +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Get string:org.asamk.Signal.Group string:$PROPERTY_NAME` + +To set a property, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Set string:org.asamk.Signal.Group string:$PROPERTY_NAME variant:$PROPERTY_TYPE:$PROPERTY_VALUE` + +To get all properties, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.GetAll string:org.asamk.Signal.Group` + +addAdmins(recipients) -> <>:: +* recipients : String array of phone numbers + +Grant admin privileges to recipients. Exceptions: Failure -setContactBlocked(number, block) -> <>:: -* number : Phone number affected by method -* block : 0=remove block , 1=blocked +addMembers(recipients) -> <>:: +* recipients : String array of phone numbers -Messages from blocked numbers will no longer be forwarded via DBus. +Add recipients to group if they are pending members; otherwise add recipients to list of requesting members. -Exceptions: InvalidNumber +Exceptions: Failure -setGroupBlocked(groupId, block) -> <>:: -* groupId : Byte array representing the internal group identifier -* block : 0=remove block , 1=blocked +disableLink() -> <>:: -Messages from blocked groups will no longer be forwarded via DBus. +Disables the group's invitation link. -Exceptions: GroupNotFound +Exceptions: Failure -joinGroup(inviteURI) -> <>:: -* inviteURI : String starting with https://signal.group which is generated when you share a group link via Signal App +enableLink(requiresApproval) -> <>:: +* requiresApproval : true=add numbers using the link to the requesting members list + +Enables the group's invitation link. Exceptions: Failure +quitGroup() -> <>:: +Exceptions: Failure, LastGroupAdmin + +removeAdmins(recipients) -> <>:: +* recipients : String array of phone numbers + +Remove admin privileges from recipients. + +Exceptions: Failure + +removeMembers(recipients) -> <>:: +* recipients : String array of phone numbers + +Remove recipients from group. + +Exceptions: Failure + +resetLink() -> <>:: + +Resets the group's invitation link to a new random URL starting with https://signal.group/# + +Exceptions: Failure + +=== Deprecated group control methods +The following deprecated methods listen to the recipient's object path, which is constructed as follows: +"/org/asamk/Signal/" + DBusNumber +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) + +getGroupIds() -> groupList:: +groupList : Array of Byte arrays representing the internal group identifiers + +All groups known are returned, regardless of their active or blocked status. To query that use isMember() and isGroupBlocked() + +Exceptions: None + +getGroupName(groupId) -> groupName:: +* groupId : Byte array representing the internal group identifier +* groupName : The display name of the group + +Exceptions: None, if the group name is not found an empty string is returned + +isGroupBlocked(groupId) -> isGroupBlocked:: +* groupId : Byte array representing the internal group identifier +* isGroupBlocked : true=group is blocked; false=group is not blocked + +Dbus will not forward messages from a group when you have blocked it. + +Exceptions: InvalidGroupId, Failure + +isMember(groupId) -> isMember:: +* groupId : Byte array representing the internal group identifier +* isMember : true=you are a group member; false=you are not a group member + +Note that this method does not raise an Exception for a non-existing/unknown group but will simply return 0 (false) + quitGroup(groupId) -> <>:: * groupId : Byte array representing the internal group identifier Note that quitting a group will not remove the group from the getGroupIds command, but set it inactive which can be tested with isMember() -Exceptions: GroupNotFound, Failure +Exceptions: GroupNotFound, Failure, InvalidGroupId -isMember(groupId) -> active:: +setGroupBlocked(groupId, block) -> <>:: * groupId : Byte array representing the internal group identifier +* block : false=remove block , true=blocked -Note that this method does not raise an Exception for a non-existing/unknown group but will simply return 0 (false) +Messages from blocked groups will no longer be forwarded via DBus. -sendEndSessionMessage(recipients) -> <>:: -* recipients : Array of phone numbers +Exceptions: GroupNotFound, InvalidGroupId -Exceptions: Failure, InvalidNumber, UntrustedIdentity +updateGroup(groupId, newName, members, avatar) -> groupId:: +* groupId : Byte array representing the internal group identifier +* newName : New name of group (empty if unchanged) +* members : String array of new members to be invited to group +* avatar : Filename of avatar picture to be set for group (empty if none) -sendGroupMessage(message, attachments, groupId) -> timestamp:: -* message : Text to send (can be UTF8) -* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) -* groupId : Byte array representing the internal group identifier -* timestamp : Can be used to identify the corresponding signal reply +Exceptions: AttachmentInvalid, Failure, InvalidNumber, GroupNotFound + +=== Device control methods +The following methods listen to the recipient's object path, which is constructed as follows: +"/org/asamk/Signal/" + DBusNumber +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) + +addDevice(deviceUri) -> <>:: +* deviceUri : URI in the form of "sgnl://linkdevice/?uuid=..." (formerly "tsdevice:/?uuid=...") Normally displayed by a Signal desktop app, smartphone app, or another signal-cli instance using the `link` control method. -Exceptions: GroupNotFound, Failure, AttachmentInvalid +getDevice(deviceId) -> devicePath:: +* deviceId : Long representing a deviceId +* devicePath : DBusPath object for the device + +Exceptions: DeviceNotFound + +listDevices() -> devices:: +* devices : Array of structs (objectPath, id, name) +** objectPath : DBusPath representing the device's object path +** id : Long representing the deviceId +** name : String representing the device's name + +Exceptions: InvalidUri sendContacts() -> <>:: @@ -188,206 +337,194 @@ sendSyncRequest() -> <>:: Sends a synchronization request to the primary device (for group, contacts, ...). Only works if sent from a secondary device. -Exception: Failure - -sendNoteToSelfMessage(message, attachments) -> timestamp:: -* message : Text to send (can be UTF8) -* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) -* timestamp : Can be used to identify the corresponding signal reply +Exceptions: Failure -Exceptions: Failure, AttachmentInvalid +=== Device methods and properties +The following methods listen to the device's object path, which is constructed as follows: +"/org/asamk/Signal/" + DBusNumber + "/Devices/" + deviceId +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) +* deviceId : Long representing the device identifier (obtained from listDevices() method) -sendMessage(message, attachments, recipient) -> timestamp:: -sendMessage(message, attachments, recipients) -> timestamp:: -* message : Text to send (can be UTF8) -* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) -* recipient : Phone number of a single recipient -* recipients : Array of phone numbers -* timestamp : Can be used to identify the corresponding signal reply +Devices have the following (case-sensitive) properties: +* Id (read-only) : Long representing the device identifier +* Created (read-only) : Long representing the number of milliseconds since the Unix epoch +* LastSeen (read-only) : Long representing the number of milliseconds since the Unix epoch +* Name : String representing the display name of the device -Depending on the type of the recipient field this sends a message to one or multiple recipients. +To get a property, use (replacing `--session` with `--system` if needed): +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Get string:org.asamk.Signal.Device string:$PROPERTY_NAME` -Exceptions: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity +To set a property, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Set string:org.asamk.Signal.Device string:$PROPERTY_NAME variant:$PROPERTY_TYPE:$PROPERTY_VALUE` -sendTyping(recipient, stop) -> <>:: -* recipient : Phone number of a single recipient -* targetSentTimestamp : True, if typing state should be stopped - -Exceptions: Failure, GroupNotFound, UntrustedIdentity +To get all properties, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.GetAll string:org.asamk.Signal.Device` +removeDevice() -> <>:: -sendReadReceipt(recipient, targetSentTimestamp) -> <>:: -* recipient : Phone number of a single recipient -* targetSentTimestamp : Array of Longs to identify the corresponding signal messages +Exceptions: Failure -Exceptions: Failure, UntrustedIdentity +=== Configuration properties +The configuration's object path, which exists only for primary devices, is constructed as follows: +"/org/asamk/Signal/" + DBusNumber + "/Configuration" +* DBusNumber : recipient's phone number, with underscore (_) replacing plus (+) -sendGroupMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, groupId) -> timestamp:: -* emoji : Unicode grapheme cluster of the emoji -* remove : Boolean, whether a previously sent reaction (emoji) should be removed -* targetAuthor : String with the phone number of the author of the message to which to react -* targetSentTimestamp : Long representing timestamp of the message to which to react -* groupId : Byte array with base64 encoded group identifier -* timestamp : Long, can be used to identify the corresponding signal reply +Configurations have the following (case-sensitive) properties: +* ConfigurationReadReceipts : should send read receipts (true/false) +* ConfigurationUnidentifiedDeliveryIndicators : should show unidentified delivery indicators (true/false) +* ConfigurationTypingIndicators : should send/show typing indicators (true/false) +* ConfigurationLinkPreviews : should generate link previews (true/false) -Exceptions: Failure, InvalidNumber, GroupNotFound +To get a property, use (replacing `--session` with `--system` if needed): +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Get string:org.asamk.Signal.Configuration string:$PROPERTY_NAME` -sendMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, recipient) -> timestamp:: -sendMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, recipients) -> timestamp:: -* emoji : Unicode grapheme cluster of the emoji -* remove : Boolean, whether a previously sent reaction (emoji) should be removed -* targetAuthor : String with the phone number of the author of the message to which to react -* targetSentTimestamp : Long representing timestamp of the message to which to react -* recipient : String with the phone number of a single recipient -* recipients : Array of strings with phone numbers, should there be more recipients -* timestamp : Long, can be used to identify the corresponding signal reply +To set a property, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.Set string:org.asamk.Signal.Configuration string:$PROPERTY_NAME variant:$PROPERTY_TYPE:$PROPERTY_VALUE` -Depending on the type of the recipient(s) field this sends a reaction to one or multiple recipients. +To get all properties, use: +`dbus-send --session --dest=org.asamk.Signal --print-reply $OBJECT_PATH org.freedesktop.DBus.Properties.GetAll string:org.asamk.Signal.Configuration` -Exceptions: Failure, InvalidNumber +=== Other methods -sendGroupRemoteDeleteMessage(targetSentTimestamp, groupId) -> timestamp:: -* targetSentTimestamp : Long representing timestamp of the message to delete -* groupId : Byte array with base64 encoded group identifier -* timestamp : Long, can be used to identify the corresponding signal reply +getContactName(number) -> name:: +* number : Phone number +* name : Contact's name in local storage (from the master device for a linked account, or the one set with setContactName); if not set, contact's profile name is used -Exceptions: Failure, GroupNotFound +Exceptions: None -sendRemoteDeleteMessage(targetSentTimestamp, recipient) -> timestamp:: -sendRemoteDeleteMessage(targetSentTimestamp, recipients) -> timestamp:: -* targetSentTimestamp : Long representing timestamp of the message to delete -* recipient : String with the phone number of a single recipient -* recipients : Array of strings with phone numbers, should there be more recipients -* timestamp : Long, can be used to identify the corresponding signal reply +getContactNumber(name) -> numbers:: +* numbers : Array of phone number +* name : Contact or profile name ("firstname lastname") -Depending on the type of the recipient(s) field this deletes a message with one or multiple recipients. +Searches contacts and known profiles for a given name and returns the list of all known numbers. May result in e.g. two entries if a contact and profile name is set. -Exceptions: Failure, InvalidNumber +Exceptions: None -getContactName(number) -> name:: -* number : Phone number -* name : Contact's name in local storage (from the primary device for a linked account, or the one set with setContactName); if not set, contact's profile name is used +getSelfNumber() -> number:: +* number : Your phone number -setContactName(number,name<>) -> <>:: -* number : Phone number -* name : Name to be set in contacts (in local storage with signal-cli) +Exceptions: None -getGroupIds() -> groupList:: -groupList : Array of Byte arrays representing the internal group identifiers +isContactBlocked(number) -> blocked:: +* number : Phone number +* blocked : true=blocked, false=not blocked -All groups known are returned, regardless of their active or blocked status. To query that use isMember() and isGroupBlocked() +For unknown numbers false is returned but no exception is raised. -getGroupName(groupId) -> groupName:: -groupName : The display name of the group -groupId : Byte array representing the internal group identifier +Exceptions: InvalidPhoneNumber -Exceptions: None, if the group name is not found an empty string is returned +isRegistered() -> result:: +isRegistered(number) -> result:: +isRegistered(numbers) -> results:: +* number : Phone number +* numbers : String array of phone numbers +* result : true=number is registered, false=number is not registered +* results : Boolean array of results -getGroupMembers(groupId) -> members:: -members : String array with the phone numbers of all active members of a group -groupId : Byte array representing the internal group identifier +For unknown numbers, false is returned, but no exception is raised. If no number is given, returns true (indicating that you are registered). -Exceptions: None, if the group name is not found an empty array is returned +Exceptions: InvalidNumber listNumbers() -> numbers:: -numbers : String array of all known numbers +* numbers : String array of all known numbers This is a concatenated list of all defined contacts as well of profiles known (e.g. peer group members or sender of received messages) -getContactNumber(name) -> numbers:: -* numbers : Array of phone number -* name : Contact or profile name ("firstname lastname") - -Searches contacts and known profiles for a given name and returns the list of all known numbers. May result in e.g. two entries if a contact and profile name is set. +Exceptions: None -isContactBlocked(number) -> state:: -* number : Phone number -* state : 1=blocked, 0=not blocked +removePin() -> <>:: -Exceptions: None, for unknown numbers 0 (false) is returned +Removes registration PIN protection. -isGroupBlocked(groupId) -> state:: -* groupId : Byte array representing the internal group identifier -* state : 1=blocked, 0=not blocked +Exceptions: Failure -Exceptions: None, for unknown groups 0 (false) is returned +sendEndSessionMessage(recipients) -> <>:: +* recipients : Array of phone numbers -removePin() -> <>:: +Exceptions: Failure, InvalidNumber, UntrustedIdentity -Removes registration PIN protection. +sendMessage(message, attachments, recipient) -> timestamp:: +sendMessage(message, attachments, recipients) -> timestamp:: +* message : Text to send (can be UTF8) +* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) +* recipient : Phone number of a single recipient +* recipients : String array of phone numbers +* timestamp : Long, can be used to identify the corresponding Signal reply -Exception: Failure +Depending on the type of the recipient field this sends a message to one or multiple recipients. -setPin(pin) -> <>:: -* pin : PIN you set after registration (resets after 7 days of inactivity) +Exceptions: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity -Sets a registration lock PIN, to prevent others from registering your number. +sendMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, recipient) -> timestamp:: +sendMessageReaction(emoji, remove, targetAuthor, targetSentTimestamp, recipients) -> timestamp:: +* emoji : Unicode grapheme cluster of the emoji +* remove : Boolean, whether a previously sent reaction (emoji) should be removed +* targetAuthor : String with the phone number of the author of the message to which to react +* targetSentTimestamp : Long representing timestamp of the message to which to react +* recipient : String with the phone number of a single recipient +* recipients : Array of strings with phone numbers, should there be more recipients +* timestamp : Long, can be used to identify the corresponding Signal reply -Exception: Failure +Depending on the type of the recipient(s) field this sends a reaction to one or multiple recipients. -version() -> version:: -* version : Version string of signal-cli +Exceptions: Failure, InvalidNumber -isRegistered() -> result:: -isRegistered(number) -> result:: -isRegistered(numbers) -> results:: -* number : Phone number -* numbers : String array of phone numbers -* result : true=number is registered, false=number is not registered -* results : Boolean array of results +sendNoteToSelfMessage(message, attachments) -> timestamp:: +* message : Text to send (can be UTF8) +* attachments : String array of filenames to send as attachments (passed as filename, so need to be readable by the user signal-cli is running under) +* timestamp : Long, can be used to identify the corresponding Signal reply -Exception: InvalidNumber for an incorrectly formatted phone number. For unknown numbers, false is returned, but no exception is raised. If no number is given, returns whether you are registered (presumably true). +Exceptions: Failure, AttachmentInvalid -addDevice(deviceUri) -> <>:: -* deviceUri : URI in the form of tsdevice:/?uuid=... Normally received from Signal desktop or smartphone app +sendReadReceipt(recipient, targetSentTimestamps) -> <>:: +* recipient : Phone number of a single recipient +* targetSentTimestamps : Array of Longs to identify the corresponding Signal messages -Exception: InvalidUri +Exceptions: Failure, UntrustedIdentity -listDevices() -> devices:: -* devices : Array of structs (objectPath, id, name) -** objectPath : DBusPath representing the device's object path -** id : Long representing the deviceId -** name : String representing the device's name +sendRemoteDeleteMessage(targetSentTimestamp, recipient) -> timestamp:: +sendRemoteDeleteMessage(targetSentTimestamp, recipients) -> timestamp:: +* targetSentTimestamp : Long representing timestamp of the message to delete +* recipient : String with the phone number of a single recipient +* recipients : Array of strings with phone numbers, should there be more recipients +* timestamp : Long, can be used to identify the corresponding signal reply -Exception: Failure +Depending on the type of the recipient(s) field this deletes a message with one or multiple recipients. -removeDevice(deviceId) -> <>:: -* deviceId : Device ID to remove, obtained from listDevices() command +Exceptions: Failure, InvalidNumber -Exception: Failure +sendTyping(recipient, stop) -> <>:: +* recipient : Phone number of a single recipient +* targetSentTimestamp : True, if typing state should be stopped -updateDeviceName(deviceName) -> <>:: -* deviceName : New name +Exceptions: Failure, GroupNotFound, UntrustedIdentity -Set a new name for this device (main or linked). +setContactBlocked(number, block) -> <>:: +* number : Phone number affected by method +* block : false=remove block, true=blocked -Exception: Failure +Messages from blocked numbers will no longer be forwarded via DBus. -uploadStickerPack(stickerPackPath) -> url:: -* stickerPackPath : Path to the manifest.json file or a zip file in the same directory -* url : URL of sticker pack after successful upload +Exceptions: InvalidNumber -Exception: Failure, IOError +setContactName(number,name<>) -> <>:: +* number : Phone number +* name : Name to be set in contacts (in local storage with signal-cli) -getConfiguration() -> [readReceipts, unidentifiedDeliveryIndicators, typingIndicators, linkPreviews] -> <>:: -* readReceipts : Should Signal send read receipts (true/false). -* unidentifiedDeliveryIndicators : Should Signal show unidentified delivery indicators (true/false). -* typingIndicators : Should Signal send/show typing indicators (true/false). -* linkPreviews : Should Signal generate link previews (true/false). +Exceptions: InvalidNumber, Failure -Gets an array of four booleans as indicated. Only works from primary device. +setExpirationTimer(number, expiration) -> <>:: +* number : Phone number of recipient +* expiration : int32 for the number of seconds before messages to this recipient disappear. Set to 0 to disable expiration. -Exceptions: IOError, UserError +Exceptions: Failure, InvalidNumber -setConfiguration(readReceipts, unidentifiedDeliveryIndicators, typingIndicators, linkPreviews) -> <>:: -* readReceipts : Should Signal send read receipts (true/false). -* unidentifiedDeliveryIndicators : Should Signal show unidentified delivery indicators (true/false). -* typingIndicators : Should Signal send/show typing indicators (true/false). -* linkPreviews : Should Signal generate link previews (true/false). +setPin(pin) -> <>:: +* pin : PIN you set after registration (resets after 7 days of inactivity) -Update Signal configurations and sync them to linked devices. Only works from primary device. +Sets a registration lock PIN, to prevent others from registering your number. -Exceptions: IOError, UserError +Exceptions: Failure submitRateLimitChallenge(challenge, captcha) -> <>:: * challenge : The challenge token taken from the proof required error. @@ -396,8 +533,38 @@ Can be used to lift some rate-limits by solving a captcha. Exception: IOErrorException +updateProfile(name, about, aboutEmoji , avatar, remove) -> <>:: +updateProfile(givenName, familyName, about, aboutEmoji , avatar, remove) -> <>:: +* name : Name for your own profile (empty if unchanged) +* givenName : Given name for your own profile (empty if unchanged) +* familyName : Family name for your own profile (empty if unchanged) +* about : About message for profile (empty if unchanged) +* aboutEmoji : Emoji for profile (empty if unchanged) +* avatar : Filename of avatar picture for profile (empty if unchanged) +* remove : Set to true if the existing avatar picture should be removed + +Exceptions: Failure + +uploadStickerPack(stickerPackPath) -> url:: +* stickerPackPath : Path to the manifest.json file or a zip file in the same directory +* url : URL of sticker pack after successful upload + +Exceptions: Failure + +version() -> version:: +* version : Version string of signal-cli + +Exceptions: None + == Signals -SyncMessageReceived (timestamp, sender, destination, groupId,message, attachments):: +SyncMessageReceived (timestamp, sender, destination, groupId, message, attachments):: +* timestamp : Integer value that can be used to associate this e.g. with a sendMessage() +* sender : Phone number of the sender +* destination : DBus code for destination +* groupId : Byte array representing the internal group identifier (empty when private message) +* message : Message text +* attachments : String array of filenames in the signal-cli storage (~/.local/share/signal-cli/attachments/) + The sync message is received when the user sends a message from a linked device. ReceiptReceived (timestamp, sender):: @@ -411,7 +578,7 @@ MessageReceived(timestamp, sender, groupId, message, attachments