signal-rest-ts

About

signal-rest-ts is a TypeScript wrapper around signal-cli-rest-api. It can be used in TypeScript or JavaScript based projects, both as a module and in a browser.

Installation

npm

npm install signal-rest-ts

Usage

[!IMPORTANT] In order to use the Receive service, signal-cli-rest-api should be ran in json-rpc mode.

As a module

Get all group metadata, for all accounts

import { SignalClient } from "signal-rest-ts";

const getAllGroups = async () => {
  const signal = new SignalClient("http://localhost:8080");
  const accounts = await signal.account().getAccounts();

  const groups = await Promise.all(
    accounts.map(async (a) => {
      return await signal.group().getGroups(a);
    });
  );

  console.log(groups);
};

Send a message to a user

import { SignalClient } from "signal-rest-ts";

const sendMeAMessage = async () => {
  const signal = new SignalClient("http://localhost:8080");
  const accounts = await signal.account().getAccounts();

  const msg = await signal.message().sendMessage({
    number: accounts[0],
    message: "This is an automated message!",
    recipients: ["+1234567890"],
  });
};

Reply to messages matching a regular expression

const signal = new SignalClient("http://localhost:8080");
const accounts = await signal.account().getAccounts();

signal.receive().registerHandler(accounts[0], /^(ha){2,}/, async (context) => {
  console.log(context.sourceUuid + " -> " + context.message);
  context.reply("What's so funny?");
});

signal.receive().startReceiving(accounts[0]);

Working across all accounts

If your handler should run across all accounts associated to the API, you will want to set a handler for each account. You will also want to "start receiving" for each account. Each account's messages are listened to using a separate WebSocket.

accounts.forEach((account) => {
  signal.receive().registerHandler(account, /^\!command/, async (context) => {
    // ...
  });
  signal.receive().startReceiving(account);
}

Exiting Cleanly

It may be smart to clean up open WebSockets. Or if your application keeps running it may be because they are open. You can close all sockets using ReceiveService#stopAllReceiving().

For example, in a Node-based application:

process.on("SIGINT", () => {
  signal.receive().stopAllReceiving();
});

DOM

Target

A version of the library bundled for the DOM is built to dist/signal-web.js in the default build script. This can be included using a script tag.

<script type="text/javascript" src="signal-web.js"></script>

This will add window.SignalClient which exports the SignalClient class and can be instantiated to access the underlying services, as in the examples above.

CORS

Note that you will have to properly configure CORS, since requests to the endpoint are almost certainly going to be cross-origin.

For example, nginx can be configured to serve permissive CORS headers. Note this example is not secure. Hardening is left as an exercise for the user.

location ~/signal-api/(.*)$ {
  proxy_pass http://10.0.0.1:8080/$1$is_args$args;
  add_header 'Access-Control-Allow-Origin' '*';
  add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE';
  add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization';
  add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
}

Samples

LLM React Bot

samples/deepseek-react-bot.ts provides examples for receiving and reacting to messages using the context react method. This sample utilizes DeepSeek and reacts to ~2% of messages with an emoji representative of the message's content.

NPR Hourly News

samples/npr-hourly-news.ts is a sample script that shows how to handle commands, use the contextual reply method, and handle attachments. When the script is running, if a user types !npr the bot will fetch the podcast feed, download the latest episode, and reply with it attached.

Running Tests

To run the test suite you can simply use the npm task "test": npm run test

Contributions

Contributions are welcome. To contribute, fork the repo and make your changes, then open a pull request on this repository.

License

Released as-is under MIT license with no warranties.