Imagine that you want to use the Signal REST API in a software component that has some restrictions regarding the payload it supports. To give you a real world example: If you want to use the Signal REST API to send Signal notifications from your Synology NAS to your phone, the HTTP endpoint must have only "flat" parameters - i.e array parameters in the JSON payload aren't allowed. Since the recipients parameter in the /v2/send endpoint is a array parameter, the send endpoint cannot be used in the Synology NAS. In order to work around that limitation, you can write a small custom plugin in Lua, to create a custom send endpoint, which exposes a single recipient string instead of an array.

How to write a custom plugin

In order to use plugins, you first need to enable that feature. This can be done by setting the environment variable ENABLE_PLUGINS to true in the docker-compose.yml file.

e.g:

services:                                                                                                                                                                                                        
  signal-cli-rest-api:
    image: bbernhard/signal-cli-rest-api:latest
    environment:
      - MODE=json-rpc #supported modes: json-rpc, native, normal
      - ENABLE_PLUGINS=true #enable plugins

A valid plugin consists of a definition file (with the file ending .def) and a matching lua script file (with the file ending .lua). Both of those files must have the same filename and are placed in a folder called plugins on the host filesystem. Now, bind mount the plugins folder from your host system into the /plugins folder inside the docker container. This can be done in the docker-compose.yml file:

services:
  signal-cli-rest-api:
    image: bbernhard/signal-cli-rest-api:latest
  environment:
    - MODE=json-rpc #supported modes: json-rpc, native, normal
    - ENABLE_PLUGINS=true
  volumes:
    - "./signal-cli-config:/home/.local/share/signal-cli" 
    - "./plugins:/plugins" #map "plugins" folder on host system into docker container.

The definition file

The definition file (with the file suffix .def) contains some metadata which is necessary to properly register the new endpoint. A proper definition file looks like this:

endpoint: my-custom-send-endpoint/:number 
method: POST

The endpoint specifies the URI of the newly created endpoint. All custom endpoints are registered under the /v1/plugins endpoint. So, our my-custom-send-endpoint will be available at /v1/plugins/my-custom-endpoint. If you want to use variables inside the endpoint, prefix them with a :.

The method parameter specifies the HTTP method that is used for the endpoint registration.

The script file

The script file (with the file suffix .lua) contains the implementation of the endpoint.

Example:

local http = require("http")
local json = require("json")

local url = "http://127.0.0.1:8080/v2/send"

local customEndpointPayload = json.decode(pluginInputData.payload)

local sendEndpointPayload = {
    recipients = {customEndpointPayload.recipient},
    message = customEndpointPayload.message,
    number = pluginInputData.Params.number
}

local encodedSendEndpointPayload = json.encode(sendEndpointPayload)

response, error_message = http.request("POST", url, {
    timeout="30s",
    headers={
        Accept="*/*",
        ["Content-Type"]="application/json"
    },
    body=encodedSendEndpointPayload
})

pluginOutputData:SetPayload(response["body"])
pluginOutputData:SetHttpStatusCode(response.status_code)

What the lua script does, is parse the JSON payload from the custom request, extract the recipient and the message from the payload and the number from the URL parameter and call the /v2/send endpoint with those parameters. The HTTP status code and the body that is returned by the HTTP request is then returned to the caller (this is done via the pluginOutputData:SetPayload and pluginOutputData:SetHttpStatusCode functions.

If you now invoke the following curl command, a message gets sent:

curl -X POST -H "Content-Type: application/json" -d '{"message": "test", "recipient": "<recipient>"}' 'http://127.0.0.1:8080/v1/plugins/my-custom-send-endpoint/<registered signal number>'

Pass commands from/to the lua script

When a new plugin is registered, some parameters are automatically passed as global variables to the lua script:

pluginInputData.payload: the (JSON) payload that is passed to the custom endpoint
pluginInputData.Params: a map of all parameters that are part of the URL, which were defined in the definition file (i.e those parameters that were defined with : prefixed in the URL)

In order to return values from the lua script, the following functions are available:

pluginOutputData:SetPayload(): Set the (JSON) payload that is returned to the caller
pluginOutputData:SetHttpStatusCode(): Set the HTTP status code that is returned to the caller