nik/signal-cli
1
0
Fork 0
mirror of https://github.com/AsamK/signal-cli.git synced 2026-05-27 14:44:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated JSON RPC service (markdown)

Sebastian Scheibner 2023-09-01 12:13:26 +02:00
parent cdd50c8769
commit 4f3da872be
1 changed files with 4 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
JSON-RPC-service.md

@ -2,71 +2,10 @@ signal-cli provides a [JSON-RPC](https://www.jsonrpc.org/specification) based AP
- `jsonRpc` command accepts input on STDIN and responds on STDOUT.
This is intended to make it easier to embed signal-cli in other applications.
`signal-cli -u _USERNAME_ jsonRpc`
`signal-cli -a _ACCOUNT_ jsonRpc` or for multi-account mode `signal-cli jsonRpc`
- `daemon` command provides a UNIX or TCP socket and can handle requests from multiple clients.
`signal-cli -u _USERNAME_ daemon --socket` or for multi-account mode `signal-cli daemon --socket`
`signal-cli -a _ACCOUNT_ daemon --socket` or for multi-account mode `signal-cli daemon --socket`
See also the corresponding [man page](https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-jsonrpc.5.adoc)
## Basic usage
In JSON-RPC mode, signal-cli will read requests from stdin. Every requests must be a JSON object in a single line.
Requests must have a unique "id" value to be able to match the response to the corresponding request.
Example:
REQUEST: `{"jsonrpc":"2.0","method":"listGroups","id":"my special mark"}`
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"}`
From the command line:
`echo '{"jsonrpc":"2.0","method":"listGroups","id":"my special mark"}' | signal-cli -u +33123456789 jsonRpc`
## Receiving messages
Like in dbus daemon mode, messages are automatically received in jsonRpc mode (`--receive-mode=automatic`). Incoming messages are sent as JSON-RPC notifications.
Example:
`{"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":[]}}}}`
In order to not miss messages, automatic receiving of messages can be disabled with the `--receive-mode=manual` parameter.
REQUEST: `{"jsonrpc":"2.0","id":"id","method":"subscribeReceive"}`
RESPONSE: `{"jsonrpc":"2.0","result":0,"id":"id"}`
Messages are then sent similar to the automatic mode, but wrapped in a subscription response object:
`{"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"}}}`
## Commands
The commands available for the JSON-RPC mode are the same as the cli commands (except `register`, `verify` and `link`).
The `method` field is the command name and the parameters can be sent as the `params` object.
- Parameter names are provided in camelCase format instead of the hyphen format on the cli.
e.g.: `--group-id=ID` on the cli becomes `"groupId":"ID"`
- Parameters that can take multiple values on the command line can be provided as single json value or as json array
e.g. `--attachment ATTACH1 ATTACH2` becomes `"attachments":["ATTACH1", "ATTACH2"]`
`--attachment ATTACH` becomes `"attachment":"ATTACH"`
### Some example requests
REQUEST: `{"jsonrpc":"2.0","method":"listGroups","id":"5"}`
RESPONSE: `{"jsonrpc":"2.0","result":[...],"id":"5"}`
REQUEST: `{"jsonrpc":"2.0","method":"send","params":{"recipient":["+YYY"],"message":"MESSAGE"},"id":4}`
RESPONSE: `{"jsonrpc":"2.0","result":{"timestamp":999},"id":4}`
REQUEST: `{"jsonrpc":"2.0","method":"updateGroup","params":{"groupId":"GROUP_ID=","name":"new group name","members":["+ZZZ"],"link":"enabledWithApproval","setPermissionEditDetails":"only-admins"},"id":"someId"}`
RESPONSE: `{"jsonrpc":"2.0","result":{"timestamp":9999},"id":"someId"}`
REQUEST: `{"jsonrpc":"2.0","method":"sendSyncRequest","id":9}`
RESPONSE: `{"jsonrpc":"2.0","result":{},"id":9}`
REQUEST: `{"jsonrpc":"2.0"}`
RESPONSE: `{"jsonrpc":"2.0","error":{"code":-32600,"message":"method field must be set","data":null},"id":null}`
See the corresponding [man page](https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-jsonrpc.5.adoc) for more information.