== 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.<method> [string:<string argument>] [array:<type>:<array argument>]
+*dbus-send*
[--system | --session] [--print-reply] --type=method_call --dest="org.asamk.Signal" /org/asamk/Signal[/_<phonenum>] org.asamk.Signal.<method> [string:<string argument>] [array:<type>:<array argument>]
+Note: when daemon was started without explicit `-u USERNAME`, the `dbus-send` command requires adding the phone number in `/org/asamk/Signal/_<phonenum>`.
== Description
* <ay> : Byte Array
* <aay> : Array of Byte Arrays
* <as> : String Array
+* <ax> : Array of signed 64 bit integer
* <b> : Boolean (0|1)
* <x> : Signed 64 bit integer
* <> : no return value
== 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<s>::
+link(newDeviceName<s>) -> deviceLinkUri<s>::
+* 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<as>::
+* accountList : Array of all attached accounts in DBus object path form
+
+Exceptions: None
+
+register(number<s>, voiceVerification<b>) -> <>::
+* number : Phone number
+* voiceVerification : true = use voice verification; false = use SMS verification
+
+Exceptions: Failure, InvalidNumber, RequiresCaptcha
+
+registerWithCaptcha(number<s>, voiceVerification<b>, captcha<s>) -> <>::
+* number : Phone number
+* voiceVerification : true = use voice verification; false = use SMS verification
+* captcha : Captcha string
+
+Exceptions: Failure, InvalidNumber, RequiresCaptcha
+
+verify(number<s>, verificationCode<s>) -> <>::
+* 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<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
+
+version() -> version<s>::
+* version : Version string of signal-cli
+
+Exceptions: None
+
+=== Other methods
+
updateGroup(groupId<ay>, newName<s>, members<as>, avatar<s>) -> groupId<ay>::
* groupId : Byte array representing the internal group identifier
* newName : New name of group (empty if unchanged)
Exceptions: AttachmentInvalid, Failure, InvalidNumber, GroupNotFound
-updateProfile(newName<s>, about <s>, aboutEmoji <s>, avatar<s>, remove<b>) -> <>::
-* newName : New name for your own profile (empty if unchanged)
+updateProfile(name<s>, about<s>, aboutEmoji <s>, avatar<s>, remove<b>) -> <>::
+updateProfile(givenName<s>, familyName<s>, about<s>, aboutEmoji <s>, avatar<s>, remove<b>) -> <>::
+* 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<s>, expiration<i>) -> <>::
+* 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
isMember(groupId<ay>) -> active<b>::
* 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<as>) -> <>::
* recipients : Array of phone numbers
Exceptions: Failure, InvalidNumber, UntrustedIdentity
-sendGroupMessage(message<s>, attachments<as>, groupId<a>) -> timestamp<x>::
+sendGroupMessage(message<s>, attachments<as>, groupId<ay>) -> 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)
* groupId : Byte array representing the internal group identifier
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<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)
Exceptions: Failure, AttachmentInvalid
-sendMessage(message<s>, attachments<as>, recipient<s) -> timestamp<x>::
+sendMessage(message<s>, attachments<as>, recipient<s>) -> timestamp<x>::
sendMessage(message<s>, attachments<as>, recipients<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)
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<s>, stop<b>) -> <>::
+* recipient : Phone number of a single recipient
+* targetSentTimestamp : True, if typing state should be stopped
+
+Exceptions: Failure, GroupNotFound, UntrustedIdentity
+
+
+sendReadReceipt(recipient<s>, targetSentTimestamp<ax>) -> <>::
+* recipient : Phone number of a single recipient
+* targetSentTimestamp : Array of Longs to identify the corresponding signal messages
+
+Exceptions: Failure, UntrustedIdentity
+
+sendGroupMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, groupId<ay>) -> timestamp<x>::
+* 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<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, recipient<s>) -> timestamp<x>::
+sendMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
+* 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<x>, groupId<ay>) -> timestamp<x>::
+* 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<x>, recipient<s>) -> timestamp<x>::
+sendRemoteDeleteMessage(targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
+* 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<s>) -> name<s>::
* 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<s>,name<>) -> <>::
* number : Phone number
getGroupIds() -> groupList<aay>::
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<ay>) -> groupName<s>::
groupName : The display name of the group
* 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<s>) -> state<b>::
* number : Phone number
Exceptions: None, for unknown groups 0 (false) is returned
+removePin() -> <>::
+
+Removes registration PIN protection.
+
+Exception: 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
+
version() -> version<s>::
* version : Version string of signal-cli
-isRegistred -> result<b>::
-* result : Currently always returns 1=true
+isRegistered() -> result<b>::
+isRegistered(number<s>) -> result<b>::
+isRegistered(numbers<as>) -> results<ab>::
+* 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<s>) -> <>::
+* deviceUri : URI in the form of tsdevice:/?uuid=... Normally received from Signal desktop or smartphone app
+
+Exception: InvalidUri
+
+listDevices() -> devices<as>::
+* devices : String array of linked devices
+
+Exception: Failure
+
+removeDevice(deviceId<i>) -> <>::
+* deviceId : Device ID to remove, obtained from listDevices() command
+
+Exception: Failure
+
+updateDeviceName(deviceName<s>) -> <>::
+* deviceName : New name
+
+Set a new name for this device (main or linked).
+
+Exception: Failure
+
+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
+
+submitRateLimitChallenge(challenge<s>, captcha<s>) -> <>::
+* 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<x>, sender<s>, destination<s>, groupId<ay>,message<s>, attachments<as>)::
The sync message is received when the user sends a message from a linked device.
This signal is received whenever we get a private message or a message is posted in a group we are an active member
+== Examples
+
+Send a text message (without attachment) to a contact::
+dbus-send --print-reply --type=method_call --dest="org.asamk.Signal" /org/asamk/Signal org.asamk.Signal.sendMessage string:"Message text goes here" array:string: string:+123456789
+
+Send a group message::
+dbus-send --session --print-reply --type=method_call --dest=org.asamk.Signal /org/asamk/Signal org.asamk.Signal.sendGroupMessage string:'The message goes here' array:string:'/path/to/attachmnt1','/path/to/attachmnt2' array:byte:139,22,72,247,116,32,170,104,205,164,207,21,248,77,185
+
+Print the group name corresponding to a groupId; the daemon runs on system bus, and was started without an explicit `-u USERNAME`::
+dbus-send --system --print-reply --type=method_call --dest='org.asamk.Signal' /org/asamk/Signal/_1234567890 org.asamk.Signal.getGroupName array:byte:139,22,72,247,116,32,170,104,205,164,207,21,248,77,185
+
== Authors
Maintained by AsamK <asamk@gmx.de>, who is assisted by other open source contributors.
git.nmode.ca / signal-cli / blobdiff
