mirror of
https://github.com/aljazceru/signal-cli-rest-api.git
synced 2025-12-21 16:44:27 +01:00
108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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](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](https://signalcaptchas.org/registration/generate.html)
|
|
2. Open the developer console
|
|
3. Answer the captcha
|
|
3. 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
|
|
4. 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](https://www.home-assistant.io/integrations/signal_messenger/) for details)
|
|
|
|
## API details
|
|
|
|
Details regarding API (in example for receiving messages through REST) can be found [here](https://bbernhard.github.io/signal-cli-rest-api/)
|
|
|
|
## Troubleshooting
|
|
|
|
In case you've problems with the `signal-cli-rest-api` container, have a look [here](TROUBLESHOOTING.md)
|