JSON RPC service

signal-cli provides a JSON-RPC 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