nmode's Git Repositories - signal-cli/blob - man/signal-cli-dbus.5.adoc

   1 /////
   2 vim:set ts=4 sw=4 tw=82 noet:
   3 /////
   4 :quotes.~:
   5
   6 = signal-cli-dbus (5)
   7
   8 == Name
   9
  10 DBus API for signal-cli - A commandline and dbus interface for the Signal messenger
  11
  12 == Synopsis
  13
  14 *signal-cli* [--verbose] [--config CONFIG] [-u USERNAME] [-o {plain-text,json}] daemon [--system]
  15
  16 *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>]
  17
  18 Note: when daemon was started without explicit `-u USERNAME`, the `dbus-send` command requires adding the phone number in `/org/asamk/Signal/_<phonenum>`.
  19
  20 == Description
  21
  22 See signal-cli (1) for details on the application.
  23
  24 This documentation handles the supported methods when running signal-cli as a DBus daemon.
  25
  26 The method are described as follows:
  27
  28 method(arg1<type>, arg2<type>, ...) -> return<type>
  29
  30 Where <type> is according to DBus specification:
  31
  32 * <s>   : String
  33 * <ay>  : Byte Array
  34 * <aay> : Array of Byte Arrays
  35 * <as>  : String Array
  36 * <ax>  : Array of signed 64 bit integer
  37 * <b>   : Boolean (0|1)
  38 * <x>   : Signed 64 bit integer
  39 * <>    : no return value
  40
  41 Exceptions are the names of the Java Exceptions returned in the body field. They typically contain an additional message with details. All Exceptions begin with "org.asamk.Signal.Error." which is omitted here for better readability.
  42
  43 Phone numbers always have the format +<countrycode><regional number>
  44
  45 == Methods
  46
  47 updateGroup(groupId<ay>, newName<s>, members<as>, avatar<s>) -> groupId<ay>::
  48 * groupId  : Byte array representing the internal group identifier
  49 * newName  : New name of group (empty if unchanged)
  50 * members  : String array of new members to be invited to group
  51 * avatar   : Filename of avatar picture to be set for group (empty if none)
  52
  53 Exceptions: AttachmentInvalid, Failure, InvalidNumber, GroupNotFound
  54
  55 updateProfile(newName<s>, about <s>, aboutEmoji <s>, avatar<s>, remove<b>) -> <>::
  56 * newName     : New name for your own profile (empty if unchanged)
  57 * about       : About message for profile (empty if unchanged)
  58 * aboutEmoji  : Emoji for profile (empty if unchanged)
  59 * avatar      : Filename of avatar picture for profile (empty if unchanged)
  60 * remove      : Set to 1 if the existing avatar picture should be removed
  61
  62 Exceptions: Failure
  63
  64 setContactBlocked(number<s>, block<b>) -> <>::
  65 * number  : Phone number affected by method
  66 * block   : 0=remove block , 1=blocked
  67
  68 Messages from blocked numbers will no longer be forwarded via DBus.
  69
  70 Exceptions: InvalidNumber
  71
  72 setGroupBlocked(groupId<ay>, block<b>) -> <>::
  73 * groupId : Byte array representing the internal group identifier
  74 * block   : 0=remove block , 1=blocked
  75
  76 Messages from blocked groups will no longer be forwarded via DBus.
  77
  78 Exceptions: GroupNotFound
  79
  80 joinGroup(inviteURI<s>) -> <>::
  81 * inviteURI : String starting with https://signal.group which is generated when you share a group link via Signal App
  82
  83 Exceptions: Failure
  84
  85 quitGroup(groupId<ay>) -> <>::
  86 * groupId : Byte array representing the internal group identifier
  87
  88 Note that quitting a group will not remove the group from the getGroupIds command, but set it inactive which can be tested with isMember()
  89
  90 Exceptions: GroupNotFound, Failure
  91
  92 isMember(groupId<ay>) -> active<b>::
  93 * groupId : Byte array representing the internal group identifier
  94
  95 Note that this method does not raise an Exception for a non-existing/unknown group but will simply return 0 (false)
  96
  97 sendEndSessionMessage(recipients<as>) -> <>::
  98 * recipients : Array of phone numbers
  99
 100 Exceptions: Failure, InvalidNumber, UntrustedIdentity
 101
 102 sendGroupMessage(message<s>, attachments<as>, groupId<ay>) -> timestamp<x>::
 103 * message     : Text to send (can be UTF8)
 104 * 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)
 105 * groupId     : Byte array representing the internal group identifier
 106 * timestamp   : Can be used to identify the corresponding signal reply
 107
 108 Exceptions: GroupNotFound, Failure, AttachmentInvalid
 109
 110 sendContacts() -> <>::
 111
 112 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.
 113
 114 Exceptions: Failure
 115
 116 sendSyncRequest() -> <>::
 117
 118 Sends a synchronization request to the primary device (for group, contacts, ...). Only works if sent from a secondary device.
 119
 120 Exception: Failure
 121
 122 sendNoteToSelfMessage(message<s>, attachments<as>) -> timestamp<x>::
 123 * message     : Text to send (can be UTF8)
 124 * 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)
 125 * timestamp   : Can be used to identify the corresponding signal reply
 126
 127 Exceptions: Failure, AttachmentInvalid
 128
 129 sendMessage(message<s>, attachments<as>, recipient<s>) -> timestamp<x>::
 130 sendMessage(message<s>, attachments<as>, recipients<as>) -> timestamp<x>::
 131 * message     : Text to send (can be UTF8)
 132 * 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)
 133 * recipient   : Phone number of a single recipient
 134 * recipients  : Array of phone numbers
 135 * timestamp   : Can be used to identify the corresponding signal reply
 136
 137 Depending on the type of the recipient field this sends a message to one or multiple recipients.
 138
 139 Exceptions: AttachmentInvalid, Failure, InvalidNumber, UntrustedIdentity
 140
 141 sendTyping(recipient<s>, stop<b>) -> <>::
 142 * recipient             : Phone number of a single recipient
 143 * targetSentTimestamp   : True, if typing state should be stopped
 144
 145 Exceptions: Failure, GroupNotFound, UntrustedIdentity
 146
 147
 148 sendReadReceipt(recipient<s>, targetSentTimestamp<ax>) -> <>::
 149 * recipient             : Phone number of a single recipient
 150 * targetSentTimestamp   : Array of Longs to identify the corresponding signal messages
 151
 152 Exceptions: Failure, UntrustedIdentity
 153
 154 sendGroupMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, groupId<ay>) -> timestamp<x>::
 155 * emoji               : Unicode grapheme cluster of the emoji
 156 * remove              : Boolean, whether a previously sent reaction (emoji) should be removed
 157 * targetAuthor        : String with the phone number of the author of the message to which to react
 158 * targetSentTimestamp : Long representing timestamp of the message to which to react
 159 * groupId             : Byte array with base64 encoded group identifier
 160 * timestamp           : Long, can be used to identify the corresponding signal reply
 161
 162 Exceptions: Failure, InvalidNumber, GroupNotFound
 163
 164 sendMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, recipient<s>) -> timestamp<x>::
 165 sendMessageReaction(emoji<s>, remove<b>, targetAuthor<s>, targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
 166 * emoji               : Unicode grapheme cluster of the emoji
 167 * remove              : Boolean, whether a previously sent reaction (emoji) should be removed
 168 * targetAuthor        : String with the phone number of the author of the message to which to react
 169 * targetSentTimestamp : Long representing timestamp of the message to which to react
 170 * recipient           : String with the phone number of a single recipient
 171 * recipients          : Array of strings with phone numbers, should there be more recipients
 172 * timestamp           : Long, can be used to identify the corresponding signal reply
 173
 174 Depending on the type of the recipient(s) field this sends a reaction to one or multiple recipients.
 175
 176 Exceptions: Failure, InvalidNumber
 177
 178 sendGroupRemoteDeleteMessage(targetSentTimestamp<x>, groupId<ay>) -> timestamp<x>::
 179 * targetSentTimestamp : Long representing timestamp of the message to delete
 180 * groupId             : Byte array with base64 encoded group identifier
 181 * timestamp           : Long, can be used to identify the corresponding signal reply
 182
 183 Exceptions: Failure, GroupNotFound
 184
 185 sendRemoteDeleteMessage(targetSentTimestamp<x>, recipient<s>) -> timestamp<x>::
 186 sendRemoteDeleteMessage(targetSentTimestamp<x>, recipients<as>) -> timestamp<x>::
 187 * targetSentTimestamp : Long representing timestamp of the message to delete
 188 * recipient           : String with the phone number of a single recipient
 189 * recipients          : Array of strings with phone numbers, should there be more recipients
 190 * timestamp           : Long, can be used to identify the corresponding signal reply
 191
 192 Depending on the type of the recipient(s) field this deletes a message with one or multiple recipients.
 193
 194 Exceptions: Failure, InvalidNumber
 195
 196 getContactName(number<s>) -> name<s>::
 197 * number  : Phone number
 198 * 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
 199
 200 setContactName(number<s>,name<>) -> <>::
 201 * number  : Phone number
 202 * name    : Name to be set in contacts (in local storage with signal-cli)
 203
 204 getGroupIds() -> groupList<aay>::
 205 groupList : Array of Byte arrays representing the internal group identifiers
 206
 207 All groups known are returned, regardless of their active or blocked status. To query that use isMember() and isGroupBlocked()
 208
 209 getGroupName(groupId<ay>) -> groupName<s>::
 210 groupName : The display name of the group
 211 groupId   : Byte array representing the internal group identifier
 212
 213 Exceptions: None, if the group name is not found an empty string is returned
 214
 215 getGroupMembers(groupId<ay>) -> members<as>::
 216 members   : String array with the phone numbers of all active members of a group
 217 groupId   : Byte array representing the internal group identifier
 218
 219 Exceptions: None, if the group name is not found an empty array is returned
 220
 221 listNumbers() -> numbers<as>::
 222 numbers : String array of all known numbers
 223
 224 This is a concatenated list of all defined contacts as well of profiles known (e.g. peer group members or sender of received messages)
 225
 226 getContactNumber(name<s>) -> numbers<as>::
 227 * numbers : Array of phone number
 228 * name    : Contact or profile name ("firstname lastname")
 229
 230 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.
 231
 232 isContactBlocked(number<s>) -> state<b>::
 233 * number  : Phone number
 234 * state   : 1=blocked, 0=not blocked
 235
 236 Exceptions: None, for unknown numbers 0 (false) is returned
 237
 238 isGroupBlocked(groupId<ay>) -> state<b>::
 239 * groupId : Byte array representing the internal group identifier
 240 * state   : 1=blocked, 0=not blocked
 241
 242 Exceptions: None, for unknown groups 0 (false) is returned
 243
 244 removePin() -> <>::
 245
 246 Removes registration PIN protection.
 247
 248 Exception: Failure
 249
 250 setPin(pin<s>) -> <>::
 251 * pin               : PIN you set after registration (resets after 7 days of inactivity)
 252
 253 Sets a registration lock PIN, to prevent others from registering your number.
 254
 255 Exception: Failure
 256
 257 version() -> version<s>::
 258 * version : Version string of signal-cli
 259
 260 isRegistred -> result<b>::
 261 * result : Currently always returns 1=true
 262
 263 uploadStickerPack(stickerPackPath<s>) -> url<s>::
 264 * stickerPackPath : Path to the manifest.json file or a zip file in the same directory
 265 * url             : URL of sticker pack after successful upload
 266
 267 Exception: Failure
 268
 269 == Signals
 270
 271 SyncMessageReceived (timestamp<x>, sender<s>, destination<s>, groupId<ay>,message<s>, attachments<as>)::
 272 The sync message is received when the user sends a message from a linked device.
 273
 274 ReceiptReceived (timestamp<x>, sender<s>)::
 275 * timestamp : Integer value that can be used to associate this e.g. with a sendMessage()
 276 * sender    : Phone number of the sender
 277
 278 This signal is sent by each recipient (e.g. each group member) after the message was successfully delivered to the device
 279
 280 MessageReceived(timestamp<x>, sender<s>, groupId<ay>, message<s>, attachments<as>)::
 281 * timestamp   : Integer value that is used by the system to send a ReceiptReceived reply
 282 * sender      : Phone number of the sender
 283 * groupId     : Byte array representing the internal group identifier (empty when private message)
 284 * message     : Message text
 285 * 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
 286
 287 This signal is received whenever we get a private message or a message is posted in a group we are an active member
 288
 289 == Examples
 290
 291 Send a text message (without attachment) to a contact::
 292 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
 293
 294 Send a group message::
 295 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
 296
 297 Print the group name corresponding to a groupId; the daemon runs on system bus, and was started without an explicit `-u USERNAME`::
 298 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
 299
 300 == Authors
 301
 302 Maintained by AsamK <asamk@gmx.de>, who is assisted by other open source contributors.
 303 For more information about signal-cli development, see
 304 <https://github.com/AsamK/signal-cli>.