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

   1 /////
   2 vim:set ts=4 sw=4 tw=82 noet:
   3 /////
   4
   5 :quotes.~:
   6
   7 = signal-cli-jsonrpc (5)
   8 :doctype: manpage
   9
  10 == Name
  11
  12 signal-cli-jsonrpc - A commandline and dbus interface for the Signal messenger
  13
  14 == Synopsis
  15
  16 *signal-cli* [--verbose] [--config CONFIG] [-a ACCOUNT] daemon [--socket[=SOCKET_PATH]] [--tcp[=HOST:PORT]] [--http[=HOST:PORT]]
  17
  18 *signal-cli* [--verbose] [--config CONFIG] [-a ACCOUNT] jsonRpc
  19
  20 == Description
  21
  22 See signal-cli (1) for details on the application.
  23
  24 signal-cli provides a JSON-RPC based API with the `jsonRpc` and `daemon` commands.
  25
  26 - `jsonRpc` command accepts input on STDIN and responds on STDOUT.
  27 This is intended to make it easier to embed signal-cli in other applications.
  28
  29   `signal-cli -a _ACCOUNT_ jsonRpc` or for multi-account mode `signal-cli jsonRpc`
  30
  31 - `daemon` command provides a UNIX, TCP socket or HTTP endpoint and can handle requests from multiple clients.
  32
  33   `signal-cli -a _ACCOUNT_ daemon --socket` or for multi-account mode `signal-cli daemon --socket`
  34
  35 With `--http` signal-cli exposes three endpoints;
  36
  37 * POST /api/v1/rpc : Expects a single or batch JSON-RPC request
  38 * GET /api/v1/events : Returns a Server-Sent Events (SSE) stream of incoming messages
  39 * GET /api/v1/check : Responds with 200 OK if daemon is running
  40
  41 == Basic usage
  42
  43 In JSON-RPC mode, signal-cli will read requests from stdin.
  44 Every request must be a JSON object in a single line.
  45 Requests must have a unique "id" value to be able to match the response to the corresponding request.
  46
  47 Example:
  48
  49 REQUEST: `{"jsonrpc":"2.0","method":"listGroups","id":"my special mark"}`
  50
  51 RESPONSE: `{"jsonrpc":"2.0","result":[{"id":"Pmpi+EfPWmsxiomLe9Nx2XF9HOE483p6iKiFj65iMwI=","name":"My Group","description":"It's special because it is mine.","isMember":true,"isBlocked":false,"members":["+33123456789","+440123456789"],"pendingMembers":[],"requestingMembers":[],"admins":["+33123456789","+440123456789"],"groupInviteLink":"https://signal.group/#CjQKIAtcbUw482i7bqvmJCwdgvg0FMif52N5v9lGg_bE4U3zEhCjHKSaPzWImMpnCbU8A1r0"}],"id":"my special mark"}`
  52
  53 From the command line:
  54
  55 `echo '{"jsonrpc":"2.0","method":"listGroups","id":"my special mark"}' | signal-cli -u +33123456789 jsonRpc`
  56
  57 Like in dbus daemon mode, messages are automatically received in jsonRpc mode (`--receive-mode=on-start`).
  58 Incoming messages are sent as JSON-RPC notifications.
  59
  60 Example:
  61
  62 `{"jsonrpc":"2.0","method":"receive","params":{"envelope":{"source":"+33123456789","sourceNumber":"+33123456789","sourceUuid":"uuid","sourceName":"name","sourceDevice":1,"timestamp":1631458508784,"dataMessage":{"timestamp":1631458508784,"message":"foobar","expiresInSeconds":0,"viewOnce":false,"mentions":[],"attachments":[],"contacts":[]}}}}`
  63
  64 In order to not miss messages, automatic receiving of messages can be disabled with the `--receive-mode=manual` parameter.
  65
  66 REQUEST: `{"jsonrpc":"2.0","id":"id","method":"subscribeReceive"}`
  67
  68 RESPONSE: `{"jsonrpc":"2.0","result":0,"id":"id"}`
  69
  70 Messages are then sent similar to the automatic mode, but wrapped in a subscription response object:
  71
  72 `{"jsonrpc":"2.0","method":"receive","params":{"subscription":0,"result":{"envelope":{"source":"+33123456789","sourceNumber":"+33123456789","sourceUuid":"uuid","sourceName":"name","sourceDevice":2,"timestamp":1693064367769,"syncMessage":{"sentMessage":{"destination":"+33123456789","destinationNumber":"+33123456789","destinationUuid":"uuid","timestamp":1693064367769,"message":"j","expiresInSeconds":0,"viewOnce":false}}},"account":"+33123456789"}}}`
  73
  74 === Multi-account mode
  75
  76 When the daemon/jsonRpc command is started without an account parameter (-a), signal-cli will provide all local accounts and additional commands to register (`register`) and link (`startLink`, `finishLink`) new accounts.
  77
  78 In multi-account mode, requests for a single account require an additional `account` param.
  79
  80 REQUEST: `{"jsonrpc":"2.0","method":"listGroups","id":"my special mark","params":{"account":"+33123456789"}}`
  81
  82 == Commands
  83
  84 The commands available for the JSON-RPC mode are the same as the cli commands (except `register`, `verify` and `link`).
  85 The `method` field is the command name and the parameters can be sent as the `params` object.
  86
  87 - Parameter names are provided in camelCase format instead of the hyphen format on the cli.
  88
  89   e.g.: `--group-id=ID` on the cli becomes `"groupId":"ID"`
  90
  91 - Parameters that can take multiple values on the command line can be provided as single json value or as json array
  92
  93   e.g. `--attachment ATTACH1 ATTACH2` becomes `"attachments":["ATTACH1", "ATTACH2"]`
  94
  95   `--attachment ATTACH` becomes `"attachment":"ATTACH"`
  96
  97 === Additional JSON-RPC commands
  98
  99 ==== subscribeReceive
 100
 101 For receiving message with `--receive-mode=manual` parameter.
 102
 103 Tells the daemon to start receiving messages, returns the subscription id as a single integer value in the result.
 104
 105 ==== unsubscribeReceive
 106
 107 Stop a previous subscription for receiving messages.
 108
 109 Params:
 110
 111 - `subscription`: the subscription id returned by `subscribeReceive`
 112
 113 ==== startLink
 114
 115 Starts the provisioning for a new linked account.
 116 Responds with a URI that can be used with the `addDevice` signal-cli command or encoded as a QR-code and scanned with a mobile phone.
 117 The URI is only valid for a short amount of time.
 118
 119 REQUEST: `{"jsonrpc":"2.0","method":"startLink","id":"5"}`
 120
 121 RESPONSE: `{"jsonrpc":"2.0","result":{"deviceLinkUri":"sgnl://linkdevice?uuid=X&pub_key=X"},"id":"5"}`
 122
 123 ==== finishLink
 124
 125 Finish provisioning of a new linked account.
 126 Can be called immediately after `startLink`, it will wait for a response from the primary device.
 127
 128 Params:
 129
 130 - `deviceLinkUri`: the URI returned by `startLink`
 131 - `deviceName`: (optional) the name for the new linked device
 132
 133 REQUEST: `{"jsonrpc":"2.0","method":"finishLink","id":"6","params":{"deviceLinkUri":"sgnl://linkdevice?uuid=X&pub_key=X","deviceName":"new-name"}}`
 134
 135 RESPONSE: `{"jsonrpc":"2.0","result":{"deviceLinkUri":"sgnl://linkdevice?uuid=X&pub_key=X"},"id":"6"}`
 136
 137 == Examples
 138
 139 REQUEST: `{"jsonrpc":"2.0","method":"listGroups","id":"5"}`
 140
 141 RESPONSE: `{"jsonrpc":"2.0","result":[...],"id":"5"}`
 142
 143 REQUEST: `{"jsonrpc":"2.0","method":"send","params":{"recipient":["+YYY"],"message":"MESSAGE"},"id":4}`
 144
 145 RESPONSE: `{"jsonrpc":"2.0","result":{"timestamp":999},"id":4}`
 146
 147 REQUEST: `{"jsonrpc":"2.0","method":"updateGroup","params":{"groupId":"GROUP_ID=","name":"new group name","members":["+ZZZ"],"link":"enabledWithApproval","setPermissionEditDetails":"only-admins"},"id":"someId"}`
 148
 149 RESPONSE: `{"jsonrpc":"2.0","result":{"timestamp":9999},"id":"someId"}`
 150
 151 REQUEST: `{"jsonrpc":"2.0","method":"sendSyncRequest","id":9}`
 152
 153 RESPONSE: `{"jsonrpc":"2.0","result":{},"id":9}`
 154
 155 REQUEST: `{"jsonrpc":"2.0"}`
 156
 157 RESPONSE: `{"jsonrpc":"2.0","error":{"code":-32600,"message":"method field must be set","data":null},"id":null}`
 158
 159 == Authors
 160
 161 Maintained by AsamK <asamk@gmx.de>, who is assisted by other open source contributors.
 162 For more information about signal-cli development, see
 163 <https://github.com/AsamK/signal-cli>.