mirror of
https://github.com/AsamK/signal-cli.git
synced 2026-05-26 14:34:19 +00:00
Updated JSON service (markdown)
AsamK
parent
a4698f8ad7
commit
9c8d3b01ef
64
JSON-RPC-service.md
Normal file
64
JSON-RPC-service.md
Normal file
@ -0,0 +1,64 @@
|
||||
signal-cli provides a [JSON-RPC](https://www.jsonrpc.org/specification) based API that accepts input on STDIN and responds on STDOUT.
|
||||
The JSON-RPC mode is intended to make it easier to embed signal-cli in other applications.
|
||||
|
||||
## Basic usage
|
||||
`signal-cli -u _USERNAME_ jsonRpc`
|
||||
|
||||
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 reponse 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`
|
||||
|
||||
Like in dbus daemon mode, messages are automatically received in jsonRpc mode. Incoming messages are sent to stdout 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":[]}}}}`
|
||||
|
||||
## 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}`
|
||||
|
||||
## Communicate with named pipes
|
||||
It is possible to communicate with the server over the network using named pipes. For example, the following commands set up a JSON RPC signal-cli server listening on local port 9182:
|
||||
|
||||
mkfifo sigsocket
|
||||
(while true; do nc -l -p 9182 <sigsocket; done) | signal-cli -u +123456789 jsonRpc >sigsocket &
|
||||
|
||||
To communicate with the server from the same machine (localhost), issue the command:
|
||||
|
||||
`nc localhost 9182` <-- note that the port number must match the port number above
|
||||
@ -1,47 +0,0 @@
|
||||
signal-cli (proposed release) supports a JSON RPC server that accepts input on STDIN and replies on STDOUT. See (https://github.com/AsamK/signal-cli/discussions/679)
|
||||
|
||||
`signal-cli -u _USERNAME_ jsonRpc`
|
||||
|
||||
Note that for the `JsonRpc` command, `--output=json` is the default.
|
||||
|
||||
It is possible to communicate with the server over the network using named pipes. For example, the following commands set up a JSON RPC signal-cli server listening on local port 9182:
|
||||
|
||||
mkfifo sigsocket
|
||||
(while true; do nc -l -p 9182 <sigsocket; done) | signal-cli --output=json -u +33123456789 jsonRpc >sigsocket &
|
||||
|
||||
To communicate with the server from the same machine (localhost), issue the command:
|
||||
|
||||
`nc localhost 9182` <-- note that the port number must match the port number above
|
||||
|
||||
It will await your entries in the required format. Be sure to include the arbitrary "id" field if you want to receive a response! The response will contain the same "id" as its last field. For example:
|
||||
|
||||
ENTRY: `{"jsonrpc":"2.0","method":"listGroups","id":"my special mark"}`
|
||||
|
||||
REPLY: `{"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 --output=json -u +33123456789 jsonRpc`
|
||||
|
||||
You should receive the same response that the `nc` command provides.
|
||||
|
||||
### Converting options to camelCase
|
||||
|
||||
Several options in the command line interface contain embedded hyphens. You may send them as-is (all lowercase, with hyphens), or convert them to camelCase (in which the letter after every hyphen is capitalized and then all the hyphens are removed).
|
||||
|
||||
### Some example requests
|
||||
|
||||
ENTRY: `{"jsonrpc":"2.0","method":"listGroups","id":"5"}`
|
||||
REPLY: `{"jsonrpc":"2.0","result":[...],"id":"5"}`
|
||||
|
||||
ENTRY: `{"jsonrpc":"2.0","method":"send","params":{"recipient":["+YYY"],"message":"MESSAGE"},"id":4}`
|
||||
REPLY: `{"jsonrpc":"2.0","result":{"timestamp":999},"id":4}`
|
||||
|
||||
ENTRY: `{"jsonrpc":"2.0","method":"updateGroup","params":{"groupId":"GROUP_ID=","name":"new group name","members":["+ZZZ"],"link":"enabledWithApproval","setPermissionEditDetails":"only-admins"},"id":"someId"}`
|
||||
REPLY: `{"jsonrpc":"2.0","result":{"timestamp":9999},"id":"someId"}`
|
||||
|
||||
ENTRY: `{"jsonrpc":"2.0","method":"sendSyncRequest","id":9}`
|
||||
REPLY: `{"jsonrpc":"2.0","result":{},"id":9}`
|
||||
|
||||
ENTRY: `{"jsonrpc":"2.0"}`
|
||||
REPLY: `{"jsonrpc":"2.0","error":{"code":-32600,"message":"method field must be set","data":null},"id":null}`
|
||||
Loading…
x
Reference in New Issue
Block a user