## 🌐Used Known Ports
| Host | Description | Protocol | Port |
| ----------- | ----------- | -------- | --------------------- |
| Docker host | Signal API | TCP | 8080 (can be changed) |
## 📝Requirements
- Host with docker installed
- Existing Signal account + phone number to send messages from
- [Postman](https://www.postman.com/downloads/) for API methods
- Or any other tool you are comfortable with (e.g. curl)
## 🔧Installation
### Signal Rest API Container Installation (docker-compose)
Create new docker compose file, change port 8080 if it is already used:
```yml
# docker-compose.yml
version: "3"
services:
signal-cli-rest-api:
image: bbernhard/signal-cli-rest-api:latest
environment:
- MODE=normal
ports:
- "8080:8080"
volumes:
- "./signal-cli-config:/home/.local/share/signal-cli"
```
Run docker container:
```bash
sudo docker-compose up -d
```
Check if the container is running:
```bash
sudo docker ps
```
(Optional) Open up firewall rule:
```bash
sudo ufw allow 8080
```
#### Testing API Reachability with Postman
Method: ``
```
GET
```
URL: ``
```
http://<ContainerHost>:<SingalApiPort>/v1/about
```
Response:
```json
{
"versions": [
"v1",
"v2"
],
"build": 2,
"mode": "normal",
"version": "0.92",
"capabilities": {
"v2/send": [
"quotes",
"mentions"
]
}
}
```
#### Testing API Reachability with Curl
```bash
curl -X 'GET' \
'http://<ContainerHost>:<SignalApiPort>/v1/about' \
-H 'accept: application/json'
```
### Registering the REST API as a New Device
This part requires you to have Signal already set up on a device/phone number.
The REST API will use this existing number to send texts from.
You can also register any other number to send texts from, although the additional device method is the easiest to configure.
Open a web browser and go to the URL:
```http
http://<ContainerHost>:<SingalApiPort>/v1/qrcodelink?device_name=signal-api
```
The page should show a blank white page displaying a QR code (you might have to wait a couple of seconds).
![[_media/Untitled 112025-03-12.png||800]]
Scan the QR code inside your installed Signal app by clicking your profile picture → Settings.
![[_media/Untitled 112025-03-12-2.png||200]]
Then Connected Devices → Connect New Device.
![[_media/Untitled 112025-03-12-3.png||200]]
![[_media/Untitled 112025-03-12-4.png||200]]
Scan the QR code — the signal-api should now show up under connected devices.
![[_media/Untitled 112025-03-12-5.png||200]]
### Send a Test Message via the Signal API
#### Postman
Method: ``
```
POST
```
URL: ``
```
http://<ContainerHost>:<SignalApiPort>/v2/send
```
Body:
```json
{
"message": "Test via Signal API!",
"number": "+49<Number>",
"recipients": ["+49<Number>"]
}
```
#### Curl
```bash
curl -X 'POST' \
'http://<ContainerHost>:<SignalApiPort>/v2/send' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"message": "Test123",
"number": "+49<number>",
"recipients": ["+49<number>"]
}'
```
### Resolve Rate Limit of Signal API
Signal enforces a rate limit when sending messages to numbers other than itself.
To lower the rate limit you will need to solve a captcha and send the response to the Signal API.
Inside the response of a failed send POST you will find the `Challenge token`, in a form like this: `176f7423-e5f1-4d81-8d63-c84948f43da6`.
Note down the challenge token, then go to https://signalcaptchas.org/challenge/generate and complete the captcha.
An error might pop up — ignore it and right-click the `Open Signal` link and copy the link URL.
The copied link should look something like this:
```
signalcaptcha://signal-hcaptcha.5fad97ac-7d06-4e44-b18a-b950b20148ff.challenge.P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwYXNza2V5Ijoic214OGtqRUJnVjMzSThSZWw0UHpMQUtQY3JzSlJDakJEZ1NaaU16QmFUZjV2OGpRTlBVNC9EYlo2MEVWVmRiN2cvekdMVFFpNWdSb01HeDBsVk5nYXlGWHYveEpUb3pLdmxKL0pseDlyOCtwTFY2MDN3WXM3TmJlTVlJNlpPaHR4Z1QxZkJLTmF6dU9RRjkxTDl[...]
```
You need to paste the `Challenge Token` and the URL of the `Open Signal` link fairly quickly into the next step — you might need a couple of tries to get it in time.
#### Sending the Challenge with Postman
Method:
```
POST
```
URL:
```
http://<ContainerHost>:<SingalApiPort>/v1/accounts/%2B49<NumberWithoutCountrycode>/rate-limit-challenge
```
Body:
```json
{
"captcha": "<CopiedLink>",
"challenge_token": "<ChallengeToken>"
}
```
If you get a 200 OK response, everything worked correctly and you should be able to send Signal messages via the API to other numbers.
![[_media/Setting Up Signal Restapi and integrating it into Homeassistant2025-03-12.png]]
#### Sending Challenge with Curl
```bash
curl -X 'POST' \
'http://<ContainerHost>:<SingalApiPort>/v1/accounts/%2B49<NumberWithoutCountrycode>/rate-limit-challenge' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"captcha": "<copiedLink>",
"challenge_token": "<ChallengeToken>"
}'
```
### Using Signal Messenger in Home Assistant
#### Installing the Integration
Installation of the Signal Messenger integration is done by editing the main `configuration.yaml` file, using e.g. the Studio Code Server integration.
Add the following YAML code to your `/config/configuration.yaml` file:
```yaml
notify:
- name: signal
platform: signal_messenger
url: "http://<ContainerHost>:<SignalApiPort>"
number: "+49<Number>"
recipients:
- "+49<Number>"
```
Restart Home Assistant for the configuration file to reload.
#### Test the Integration
Create a new test automation to check if Home Assistant notifications can be sent through the Signal API:
```yml
alias: Signal Test
description: test Signal
triggers: []
conditions: []
actions:
- action: notify.signal
metadata: {}
data:
message: test
title: test
mode: single
```
## 🔗Resources
### Postman
- https://www.postman.com/downloads/
### signal-cli-restapi
- https://github.com/bbernhard/signal-cli-rest-api
- https://bbernhard.github.io/signal-cli-rest-api/