signal-cli-rest-api/doc/HOMEASSISTANT.md

README

This document describes how to use the Signal Messenger REST API together with Home Assistant.

prerequisites:

• docker + docker-compose

-or-

• ability to install Home Assistant add-ons

• a phone number to send signal notifications

Set up the docker container

• Create a docker-compose.yml file with the following contents:

version: "3"
services:
  signal-cli-rest-api:
    image: bbernhard/signal-cli-rest-api:latest
    ports:
      - "8080:8080" # map docker port 8080 to host port 8080.
    volumes:
      - "./signal-cli-config:/home/.local/share/signal-cli" # map "signal-cli-config" folder on host system into docker container. the folder contains the password and cryptographic keys when a new number is registered

• start the docker container with docker-compose up

Or Install Home Assistant Add-on

Add this repository to your Home Assistant Add-on Store reposity list:

https://github.com/haberda/hassio_addons

Then install and start the add-on.

Register phone number

In order to send signal messages to other users, you first need to register your phone number. This can be done via REST requests with:

curl -X POST -H "Content-Type: application/json" 'http://<ip>:<port>/v1/register/<number>'

e.g:

This registers the number +431212131491291 to the Signal network.

curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291'

After you've sent the registration request, you will receive a token via SMS for verfication. In order to complete the registration process you need to send the verification token back via the following REST request:

curl -X POST -H "Content-Type: application/json" 'http://<ip>:<port>/v1/register/<number>/verify/<verification code>'

e.g:

curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291/verify/123-456'

If you are trying to verify a number that has PIN assigned to it you will get an error message saying: "Verification failed! This number is locked with a pin". You can provide the PIN using "--data '{"pin": "your registration lock pin"}'" to the curl verification call:

curl -X POST -H "Content-Type: application/json" --data '{"pin": "your registration lock pin"}' 'http://127.0.0.1:8080/v1/register/+431212131491291/verify/123-456'

When you try to register a number, if you receive a response like {"error":"Captcha required for verification (null)\n"} then Signal is requiring a captcha. To register the number you must do the following (in Mozilla Firefox):

1. Go to https://signalcaptchas.org/registration/generate.html
2. Open the developer console
3. Answer the captcha
4. On the developer console, find the line that looks like this: Prevented navigation to “signalcaptcha://{captcha value}” due to an unknown protocol. Copy the captcha value
5. Use it to make the registration call like this:

curl -X POST -H "Content-Type: application/json" -d '{"captcha":"captcha value"}' 'http://127.0.0.1:8080/v1/register/<number>

Sending messages to Signal Messenger groups

The signal-cli-rest-api docker container is also capable of sending messages to a Signal Messenger group.

Requirements:

• Home Assistant Version >= 0.110
• signal-cli-rest-api build-nr >= 2 The build number can be checked with: curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/about'
• your phone number needs to be properly registered (see the "Register phone number" section above on how to do that)

A new Signal Messenger group can be created with the following REST API request:

curl -X POST -H "Content-Type: application/json" -d '{"name": "<name of the group>", "members": ["<member1>", "<member2>"]}' 'http://127.0.0.1:8080/v1/groups/<number>'

e.g:

This creates a new Signal Messenger group called my group with the members +4354546464654 and +4912812812121.

curl -X POST -H "Content-Type: application/json" -d '{"name": "my group", "members": ["+4354546464654", "+4912812812121"]}' 'http://127.0.0.1:8080/v1/groups/+431212131491291'

Next, use the following endpoint to obtain the group id:

curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/<number>'

The group id then needs to be added to the Signal Messenger's recipients list in the configuration.yaml. (see here for details)

API details

Details regarding API (in example for receiving messages through REST) can be found here

Troubleshooting

In case you've problems with the signal-cli-rest-api container, have a look here