You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You will need to set up the phone number(s) to send notifications from using `REST` request. (You can set up multiple numbers.) In order to do so, make sure, you have `curl` installed on your system. You can then issue the commands shown below from the command line. We use the example server `127.0.0.1` on port `8080`. If you have set up a different server, you will have to change this in the commands.
50
+
51
+
For trouble shooting of common problems during setup, see below.
52
+
53
+
### Alternatives
54
+
55
+
* You can use a new phone number. This is recommended, as it enables full feature support. Land-line numbers are supported.
56
+
* You can link `signal-cli-rest-api` as a secondary device to an existing account on your mobile phone.
57
+
58
+
### Alternative 1: Register a new phone number
59
+
1. 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:
60
+
61
+
**Note**: If you want to register a land-line number, set the `use_voice` parameter to `true`. Signal will then call you on your number and speak the token to you instead of sending an SMS.
62
+
63
+
```sh
64
+
curl -X POST -H "Content-Type: application/json" --data '{"use_voice": false}' 'http://<ip>:<port>/v1/register/<number>'
65
+
```
66
+
67
+
**Example**: The following command registers the number `+431212131491291` to the Signal network.
68
+
69
+
```sh
70
+
curl -X POST -H "Content-Type: application/json" --data '{"use_voice": false}' 'http://127.0.0.1:8080/v1/register/+431212131491291'
71
+
```
72
+
73
+
2. After you've sent the registration request, you will receive a token via SMS (or it will be spoken to you) for verfication.
74
+
75
+
3. In order to complete the registration process, you need to send the verification token back via the following REST request:
41
76
42
-
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:
77
+
```sh
78
+
curl -X POST -H "Content-Type: application/json" 'http://<ip>:<port>/v1/register/<number>/verify/<verification code>'
79
+
```
43
80
44
-
`curl -X POST -H "Content-Type: application/json" 'http://<ip>:<port>/v1/register/<number>'`
81
+
**Example**: The following will send a verification code for the previous example number.
45
82
46
-
e.g:
83
+
```sh
84
+
curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291/verify/123-456'
85
+
```
47
86
48
-
This registers the number `+431212131491291` to the Signal network.
87
+
### Alternative 2: Use your existing mobile phone number
88
+
It is recommended to use a fresh number. Some things might not work as expected, if you only link the REST API to an existing number. For example, if you send a notification to a group including yourself, you will not be notified. This is, because the notification is sent by yourself. Therefore, consider registering your land-line number for connecting your home to Signal.
49
89
50
-
`curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291'`
90
+
1. To link the REST API as a new device to an existing account on your mobile phone, send the following command:
51
91
52
-
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:
92
+
```sh
93
+
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/qrcodelink?device_name=<device name>'
94
+
```
53
95
54
-
`curl -X POST -H "Content-Type: application/json" 'http://<ip>:<port>/v1/register/<number>/verify/<verification code>'`
96
+
**Example**:
55
97
56
-
e.g:
98
+
```sh
99
+
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/qrcodelink?device_name=HomeAssistant'
100
+
```
57
101
58
-
`curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291/verify/123-456'`
102
+
2. This provides a QR-Code image. In case of an error a JSON object will be returned.
59
103
60
-
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:
104
+
Due to security reason of Signal, the provided QR-Code will change with each request.
4. The REST API will be linked to your main account. You can use it then to send message on your own personal behalf.
63
109
110
+
### Trouble shooting: Number is locked with a PIN
111
+
If you are trying to verify a number that has a 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:
64
112
65
-
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):
If, in step 1 above, 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):
66
119
1. Go to [https://signalcaptchas.org/registration/generate.html](https://signalcaptchas.org/registration/generate.html)
67
120
2. Open the developer console
68
121
3. Answer the captcha
69
122
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
70
123
4. Use it to make the registration call like this:
71
124
72
-
`curl -X POST -H "Content-Type: application/json" -d '{"captcha":"captcha value"}' 'http://127.0.0.1:8080/v1/register/<number>`
The `signal-cli-rest-api` docker container is also capable of sending messages to a Signal Messenger group.
77
132
78
-
Requirements:
133
+
For trouble shooting of common problems during setup, see below.
134
+
135
+
### Requirements
79
136
80
137
* Home Assistant Version >= 0.110
81
-
* signal-cli-rest-api build-nr >= 2
138
+
* `signal-cli-rest-api` build-nr >= 2
82
139
The build number can be checked with: `curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/about'`
83
140
* your phone number needs to be properly registered (see the "Register phone number" section above on how to do that)
84
141
85
-
A new Signal Messenger group can be created with the following REST API request:
142
+
### Create a new group
143
+
144
+
1. A new Signal Messenger group can be created with the following REST API request:
145
+
146
+
```sh
147
+
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>'
148
+
```
149
+
150
+
**Example**: The following creates a new Signal Messenger group called `my group` with the members `+4354546464654` and `+4912812812121`.
151
+
152
+
```sh
153
+
curl -X POST -H "Content-Type: application/json" -d '{"name": "my group", "members": ["+4354546464654", "+4912812812121"]}' 'http://127.0.0.1:8080/v1/groups/+431212131491291'
154
+
```
155
+
156
+
2. Next, use the following endpoint to obtain the `group_id`:
86
157
87
-
```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>'```
158
+
```sh
159
+
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/<number>'
160
+
```
88
161
89
-
e.g:
162
+
3. 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)
90
163
91
-
This creates a new Signal Messenger group called `my group` with the members `+4354546464654` and `+4912812812121`.
164
+
### Trouble shooting: If you receive an empty group list
92
165
93
-
```curl -X POST -H "Content-Type: application/json" -d '{"name": "my group", "members": ["+4354546464654", "+4912812812121"]}' 'http://127.0.0.1:8080/v1/groups/+431212131491291'```
166
+
In order for groups to show up in the `groups` list, try the following steps:
94
167
95
-
Next, use the following endpoint to obtain the group id:
168
+
* Use the JSON-RPC mode. This might already solve your issue.
169
+
* You might need to first `receive` data from the Signal servers. (See https://github.com/AsamK/signal-cli/issues/82.)
96
170
97
-
```curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/<number>'```
171
+
To do so, use the following REST request:
172
+
173
+
```sh
174
+
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/receive/<number>'
175
+
```
98
176
99
-
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)
0 commit comments