== 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<s>::
`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<as>::
* accountList : Array of all attached accounts in DBus object path form
Command fails if PIN was set after previous registration; use verifyWithPin instead.
-Exception: Failure, InvalidNumber
+Exceptions: Failure, InvalidNumber
verifyWithPin(number<s>, verificationCode<s>, pin<s>) -> <>::
* 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<s>::
* version : Version string of signal-cli
Exceptions: None
+=== Device methods
+Requests for these methods are sent to a specific device (main or linked); the list is available
+from the listDevices() method (see below under "Other methods").
+
+removeDevice() -> <>::
+
+Exceptions: Failure
+
=== Other methods
updateGroup(groupId<ay>, newName<s>, members<as>, avatar<s>) -> groupId<ay>::
* 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: Failure
+Exceptions: Failure, InvalidNumber
setContactBlocked(number<s>, block<b>) -> <>::
* number : Phone number affected by method
-* block : 0=remove block , 1=blocked
+* block : false=remove block, true=blocked
Messages from blocked numbers will no longer be forwarded via DBus.
setGroupBlocked(groupId<ay>, block<b>) -> <>::
* groupId : Byte array representing the internal group identifier
-* block : 0=remove block , 1=blocked
+* block : false=remove block , true=blocked
Messages from blocked groups will no longer be forwarded via DBus.
-Exceptions: GroupNotFound
+Exceptions: GroupNotFound, InvalidGroupId
joinGroup(inviteURI<s>) -> <>::
* inviteURI : String starting with https://signal.group which is generated when you share a group link via Signal App
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<ay>) -> active<b>::
-* groupId : Byte array representing the internal group identifier
+isMember(groupId<ay>) -> isMember<b>::
+* 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)
* 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
+* timestamp : Long, can be used to identify the corresponding Signal reply
-Exceptions: GroupNotFound, Failure, AttachmentInvalid
+Exceptions: GroupNotFound, Failure, AttachmentInvalid, InvalidGroupId
sendContacts() -> <>::
Sends a synchronization request to the primary device (for group, contacts, ...). Only works if sent from a secondary device.
-Exception: Failure
+Exceptions: Failure
sendNoteToSelfMessage(message<s>, attachments<as>) -> timestamp<x>::
* 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
+* timestamp : Long, can be used to identify the corresponding Signal reply
Exceptions: Failure, AttachmentInvalid
* 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
+* recipients : String array of phone numbers
+* timestamp : Long, can be used to identify the corresponding Signal reply
Depending on the type of the recipient field this sends a message to one or multiple recipients.
Exceptions: Failure, GroupNotFound, UntrustedIdentity
-
-sendReadReceipt(recipient<s>, targetSentTimestamp<ax>) -> <>::
+sendReadReceipt(recipient<s>, targetSentTimestamps<ax>) -> <>::
* recipient : Phone number of a single recipient
-* targetSentTimestamp : Array of Longs to identify the corresponding signal messages
+* targetSentTimestamps : Array of Longs to identify the corresponding Signal messages
Exceptions: Failure, UntrustedIdentity
* 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
+* groupId : Byte array representing the internal group identifier
* timestamp : Long, can be used to identify the corresponding signal reply
-Exceptions: Failure, InvalidNumber, GroupNotFound
+Exceptions: Failure, InvalidNumber, GroupNotFound, InvalidGroupId
sendMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, recipient<s>) -> timestamp<x>::
sendMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
* 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
+* timestamp : Long, can be used to identify the corresponding Signal reply
Depending on the type of the recipient(s) field this sends a reaction to one or multiple recipients.
* groupId : Byte array with base64 encoded group identifier
* timestamp : Long, can be used to identify the corresponding signal reply
-Exceptions: Failure, GroupNotFound
+Exceptions: Failure, GroupNotFound, InvalidGroupId
sendRemoteDeleteMessage(targetSentTimestamp<x>, recipient<s>) -> timestamp<x>::
sendRemoteDeleteMessage(targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
* 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: None
+
setContactName(number<s>,name<>) -> <>::
* number : Phone number
* name : Name to be set in contacts (in local storage with signal-cli)
+Exceptions: InvalidNumber, Failure
+
getGroupIds() -> groupList<aay>::
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<ay>) -> groupName<s>::
-groupName : The display name of the group
-groupId : Byte array representing the internal group identifier
+* 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
getGroupMembers(groupId<ay>) -> members<as>::
-members : String array with the phone numbers of all active members of a group
-groupId : Byte array representing the internal group identifier
+* 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
listNumbers() -> numbers<as>::
-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)
+Exceptions: None
+
getContactNumber(name<s>) -> numbers<as>::
* 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.
-isContactBlocked(number<s>) -> state<b>::
-* number : Phone number
-* state : 1=blocked, 0=not blocked
+Exceptions: None
-Exceptions: None, for unknown numbers 0 (false) is returned
+isContactBlocked(number<s>) -> blocked<b>::
+* number : Phone number
+* blocked : true=blocked, false=not blocked
-isGroupBlocked(groupId<ay>) -> state<b>::
-* groupId : Byte array representing the internal group identifier
-* state : 1=blocked, 0=not blocked
+For unknown numbers false is returned but no exception is raised.
+
+Exceptions: InvalidPhoneNumber
+
+isGroupBlocked(groupId<ay>) -> isGroupBlocked<b>::
+* groupId : Byte array representing the internal group identifier
+* isGroupBlocked : true=group is blocked; false=group is not blocked
-Exceptions: None, for unknown groups 0 (false) is returned
+Dbus will not forward messages from a group when you have blocked it.
+
+Exceptions: InvalidGroupId, Failure
removePin() -> <>::
Removes registration PIN protection.
-Exception: Failure
+Exceptions: Failure
setPin(pin<s>) -> <>::
* pin : PIN you set after registration (resets after 7 days of inactivity)
Sets a registration lock PIN, to prevent others from registering your number.
-Exception: Failure
+Exceptions: Failure
version() -> version<s>::
* version : Version string of signal-cli
+Exceptions: None
+
+getSelfNumber() -> number<s>::
+* number : Your phone number
+
+Exceptions: None
+
isRegistered() -> result<b>::
isRegistered(number<s>) -> result<b>::
isRegistered(numbers<as>) -> results<ab>::
* result : true=number is registered, false=number is not registered
* results : Boolean array of results
-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).
+For unknown numbers, false is returned, but no exception is raised. If no number is given, returns true (indicating that you are registered).
-addDevice(deviceUri<s>) -> <>::
-* deviceUri : URI in the form of tsdevice:/?uuid=... Normally received from Signal desktop or smartphone app
+Exceptions: InvalidNumber
-Exception: InvalidUri
+addDevice(deviceUri<s>) -> <>::
+* deviceUri : URI in the form of tsdevice:/?uuid=... Normally displayed by a Signal desktop app, smartphone app, or another signal-cli instance using the `link` control method.
listDevices() -> devices<a(oxs)>::
* devices : Array of structs (objectPath, id, name)
** id : Long representing the deviceId
** name : String representing the device's name
-Exception: Failure
-
-removeDevice(deviceId<i>) -> <>::
-* deviceId : Device ID to remove, obtained from listDevices() command
-
-Exception: Failure
-
-updateDeviceName(deviceName<s>) -> <>::
-* deviceName : New name
+Exceptions: InvalidUri
-Set a new name for this device (main or linked).
+getDevice(deviceId<x>) -> devicePath<o>::
+* deviceId : Long representing a (potential) deviceId
+* devicePath : DBusPath object for the device
-Exception: Failure
+Exceptions: DeviceNotFound
uploadStickerPack(stickerPackPath<s>) -> url<s>::
* stickerPackPath : Path to the manifest.json file or a zip file in the same directory
* url : URL of sticker pack after successful upload
-Exception: Failure
+Exceptions: Failure
submitRateLimitChallenge(challenge<s>, captcha<s>) -> <>::
* challenge : The challenge token taken from the proof required error.
Exception: IOErrorException
== Signals
-SyncMessageReceived (timestamp<x>, sender<s>, destination<s>, groupId<ay>,message<s>, attachments<as>)::
+SyncMessageReceived (timestamp<x>, sender<s>, destination<s>, groupId<ay>, message<s>, attachments<as>)::
+* 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<x>, sender<s>)::
* sender : Phone number of the sender
* groupId : Byte array representing the internal group identifier (empty when private message)
* message : Message text
-* attachments : String array of filenames for the attachments. These files are located in the signal-cli storage and the current user needs to have read access there
+* attachments : String array of filenames in the signal-cli storage (~/.local/share/signal-cli/attachments/)
This signal is received whenever we get a private message or a message is posted in a group we are an active member
git.nmode.ca / signal-cli / commitdiff
