X-Git-Url: https://git.nmode.ca/signal-cli/blobdiff_plain/caf16231aaf7550cedf74c66f5ddfa9a82b7bb88..d4838bd646c736a5fe1d40b45aa12be239b01ed3:/man/signal-cli-dbus.5.adoc diff --git a/man/signal-cli-dbus.5.adoc b/man/signal-cli-dbus.5.adoc index 61091d4b..594c2941 100755 --- a/man/signal-cli-dbus.5.adoc +++ b/man/signal-cli-dbus.5.adoc @@ -11,10 +11,11 @@ DBus API for signal-cli - A commandline and dbus interface for the Signal messen == Synopsis -*signal-cli* [--config CONFIG] daemon --dbus-system +*signal-cli* [--verbose] [--config CONFIG] [-u USERNAME] [-o {plain-text,json}] daemon [--system] -*dbus-send* --system --type=method_call --print-reply --dest="org.asamk.Signal" /org/asamk/Signal org.asamk.Signal. [string:] [array::] +*dbus-send* [--system | --session] [--print-reply] --type=method_call --dest="org.asamk.Signal" /org/asamk/Signal[/_] org.asamk.Signal. [string:] [array::] +Note: when daemon was started without explicit `-u USERNAME`, the `dbus-send` command requires adding the phone number in `/org/asamk/Signal/_`. == Description @@ -32,6 +33,7 @@ Where is according to DBus specification: * : Byte Array * : Array of Byte Arrays * : String Array +* : Array of signed 64 bit integer * : Boolean (0|1) * : Signed 64 bit integer * <> : no return value @@ -42,6 +44,64 @@ 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 (_). +Only `version()` is activated in single-user mode; the rest are disabled. + +link() -> deviceLinkUri:: +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 +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 + +listAccounts() -> accountList:: +* accountList : Array of all attached accounts in DBus object path form + +Exceptions: None + +register(number, voiceVerification) -> <>:: +* number : Phone number +* voiceVerification : true = use voice verification; false = use SMS verification + +Exceptions: Failure, InvalidNumber, RequiresCaptcha + +registerWithCaptcha(number, voiceVerification, captcha) -> <>:: +* number : Phone number +* voiceVerification : true = use voice verification; false = use SMS verification +* captcha : Captcha string + +Exceptions: Failure, InvalidNumber, RequiresCaptcha + +verify(number, verificationCode) -> <>:: +* number : Phone number +* verificationCode : Code received from Signal after successful registration request + +Command fails if PIN was set after previous registration; use verifyWithPin instead. + +Exception: 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 + +version() -> version:: +* version : Version string of signal-cli + +Exceptions: None + +=== Other methods + updateGroup(groupId, newName, members, avatar) -> groupId:: * groupId : Byte array representing the internal group identifier * newName : New name of group (empty if unchanged) @@ -50,12 +110,22 @@ updateGroup(groupId, newName, members, avatar) -> groupId:: Exceptions: AttachmentInvalid, Failure, InvalidNumber, GroupNotFound -updateProfile(newName, about , aboutEmoji , avatar, remove) -> <>:: -* newName : New name for your own profile (empty if unchanged) +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 picutre for profile (empty if unchanged) -* remove : Set to 1 if the existing avatar picture should be removed +* avatar : Filename of avatar picture for profile (empty if unchanged) +* remove : Set to true if the existing avatar picture should be removed + +Exceptions: Failure + + +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: Failure @@ -90,14 +160,14 @@ Exceptions: GroupNotFound, Failure isMember(groupId) -> active:: * groupId : Byte array representing the internal group identifier -Note that this method not raise an Exception for a non-existing/unknown group but will simply return 0 (false) +Note that this method does not raise an Exception for a non-existing/unknown group but will simply return 0 (false) sendEndSessionMessage(recipients) -> <>:: * recipients : Array of phone numbers Exceptions: Failure, InvalidNumber, UntrustedIdentity -sendGroupMessage(message, attachments, groupId) -> timestamp:: +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 @@ -105,6 +175,18 @@ sendGroupMessage(message, attachments, groupId) -> timestamp:: Exceptions: GroupNotFound, Failure, AttachmentInvalid +sendContacts() -> <>:: + +Sends a synchronization message with the local contacts list to all linked devices. This command should only be used if this is the primary device. + +Exceptions: Failure + +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) @@ -112,7 +194,7 @@ sendNoteToSelfMessage(message, attachments) -> timestamp:: Exceptions: Failure, AttachmentInvalid -sendMessage(message, attachments, recipient timestamp:: +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) @@ -122,11 +204,66 @@ sendMessage(message, attachments, recipients) -> timestamp:: Depending on the type of the recipient field this sends a message to one or multiple recipients. -Expections: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity +Exceptions: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity + +sendTyping(recipient, stop) -> <>:: +* recipient : Phone number of a single recipient +* targetSentTimestamp : True, if typing state should be stopped + +Exceptions: Failure, GroupNotFound, UntrustedIdentity + + +sendReadReceipt(recipient, targetSentTimestamp) -> <>:: +* recipient : Phone number of a single recipient +* targetSentTimestamp : Array of Longs to identify the corresponding signal messages + +Exceptions: Failure, UntrustedIdentity + +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 + +Exceptions: Failure, InvalidNumber, GroupNotFound + +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 + +Depending on the type of the recipient(s) field this sends a reaction to one or multiple recipients. + +Exceptions: Failure, InvalidNumber + +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 + +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 + +Depending on the type of the recipient(s) field this deletes a message with one or multiple recipients. + +Exceptions: Failure, InvalidNumber getContactName(number) -> name:: * number : Phone number -* name : Name set in contacts (setContacts) or if not set the profile name +* 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 setContactName(number,name<>) -> <>:: * number : Phone number @@ -135,7 +272,7 @@ setContactName(number,name<>) -> <>:: getGroupIds() -> groupList:: groupList : Array of Byte arrays representing the internal group identifiers -All groups known are returned, regardsless of their active or blocked status. To query that use isMember() and isGroupBlocked() +All groups known are returned, regardless of their active or blocked status. To query that use isMember() and isGroupBlocked() getGroupName(groupId) -> groupName:: groupName : The display name of the group @@ -158,7 +295,7 @@ getContactNumber(name) -> numbers:: * numbers : Array of phone number * name : Contact or profile name ("firstname lastname") -Searches contacts and know profiles for a given name and returns the list of all known names. May result in e.g. two entries if a contact and profile name is set. +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) -> state:: * number : Phone number @@ -172,14 +309,68 @@ isGroupBlocked(groupId) -> state:: Exceptions: None, for unknown groups 0 (false) is returned +removePin() -> <>:: + +Removes registration PIN protection. + +Exception: Failure + +setPin(pin) -> <>:: +* 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 + version() -> version:: * version : Version string of signal-cli -isRegistred -> result:: -* result : Currently always returns 1=true +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 -== Signals +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). +addDevice(deviceUri) -> <>:: +* deviceUri : URI in the form of tsdevice:/?uuid=... Normally received from Signal desktop or smartphone app + +Exception: InvalidUri + +listDevices() -> devices:: +* devices : String array of linked devices + +Exception: Failure + +removeDevice(deviceId) -> <>:: +* deviceId : Device ID to remove, obtained from listDevices() command + +Exception: Failure + +updateDeviceName(deviceName) -> <>:: +* deviceName : New name + +Set a new name for this device (main or linked). + +Exception: 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 + +Exception: Failure + +submitRateLimitChallenge(challenge, captcha) -> <>:: +* challenge : The challenge token taken from the proof required error. +* captcha : The captcha token from the solved captcha on the Signal website.. +Can be used to lift some rate-limits by solving a captcha. + +Exception: IOErrorException + +== Signalss SyncMessageReceived (timestamp, sender, destination, groupId,message, attachments):: The sync message is received when the user sends a message from a linked device. @@ -198,6 +389,17 @@ MessageReceived(timestamp, sender, groupId, message, attachments, who is assisted by other open source contributors.