Merge branch 'groups'

bbernhard · Apr 18, 2020 · 5cd4b8a · 5cd4b8a
2 parents a70f0a9 + 602843a
commit 5cd4b8a
Show file tree

Hide file tree

Showing 4 changed files with 351 additions and 112 deletions.
diff --git a/README.md b/README.md
@@ -1,78 +1,114 @@
-# Dockerized Signal Messenger REST API
-
-This project creates a small dockerized REST API around [signal-cli](https://github.com/AsamK/signal-cli).
-
-
-At the moment, the following functionality is exposed via REST: 
-
-* Register a number
-* Verify the number using the code received via SMS
-* Send message (+ attachment) to multiple recipients
-
-
-## Examples 
-
-Sample `docker-compose.yml`file: 
-
-```
-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.
-    network_mode: "host"
-    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
-
-```
-
-Sample REST API calls:
-
-* Register a number (with SMS verification)
-
-```curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/<number>'```
-
-   e.g:
-
-   ```curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291'```
-
-* Register a number (with voice verification)
-
-```curl -X POST -H "Content-Type: application/json" --data '{"use_voice": true}' 'http://127.0.0.1:8080/v1/register/<number>'```
-
-   e.g:
-
-   ```curl -X POST -H "Content-Type: application/json" --data '{"use_voice": true}' 'http://127.0.0.1:8080/v1/register/+431212131491291'```
-
-* Verify the number using the code received via SMS/voice
-
-   ```curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/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'```
-
-* Send message to multiple recipients
-
-   ```curl -X POST -H "Content-Type: application/json" -d '{"message": "<message>", "number": "<number>", "recipients": ["<recipient1>", "<recipient2>"]}' 'http://127.0.0.1:8080/v1/send'```
-
-   e.g:
-
-   ```curl -X POST -H "Content-Type: application/json" -d '{"message": "Hello World!", "number": "+431212131491291", "recipients": ["+4354546464654", "+4912812812121"]}' 'http://127.0.0.1:8080/v1/send'```
-
-* Send a message (+ base64 encoded attachment) to multiple recipients 
-
-  ```curl -X POST -H "Content-Type: application/json" -d '{"message": "<message>", "base64_attachment": "<base64 encoded attachment>", "number": "<number>", "recipients": ["<recipient1>", "<recipient2>"]}' 'http://127.0.0.1:8080/v1/send'```
-
-* Receive messages
-
-  Fetch all new messages in the inbox of the specified number.
-
-   ```curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/receive/<number>'```
-
-   e.g:
-
-   ```curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/receive/+431212131491291'```
-
-In case you need more functionality, please **file a ticket** or **create a PR**
+# Dockerized Signal Messenger REST API
+
+This project creates a small dockerized REST API around [signal-cli](https://github.com/AsamK/signal-cli).
+
+
+At the moment, the following functionality is exposed via REST: 
+
+* Register a number
+* Verify the number using the code received via SMS
+* Send message (+ attachment) to multiple recipients
+
+
+## Examples 
+
+Sample `docker-compose.yml`file: 
+
+```
+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.
+    network_mode: "host"
+    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
+
+```
+
+Sample REST API calls:
+
+* Register a number (with SMS verification)
+
+```curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/<number>'```
+
+   e.g:
+
+   ```curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291'```
+
+* Register a number (with voice verification)
+
+```curl -X POST -H "Content-Type: application/json" --data '{"use_voice": true}' 'http://127.0.0.1:8080/v1/register/<number>'```
+
+   e.g:
+
+   ```curl -X POST -H "Content-Type: application/json" --data '{"use_voice": true}' 'http://127.0.0.1:8080/v1/register/+431212131491291'```
+
+* Verify the number using the code received via SMS/voice
+
+   ```curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/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'```
+
+* Send message to multiple recipients
+
+   ```curl -X POST -H "Content-Type: application/json" -d '{"message": "<message>", "number": "<number>", "recipients": ["<recipient1>", "<recipient2>"]}' 'http://127.0.0.1:8080/v1/send'```
+
+   e.g:
+
+   ```curl -X POST -H "Content-Type: application/json" -d '{"message": "Hello World!", "number": "+431212131491291", "recipients": ["+4354546464654", "+4912812812121"]}' 'http://127.0.0.1:8080/v1/send'```
+
+* Send a message (+ base64 encoded attachment) to multiple recipients 
+
+  ```curl -X POST -H "Content-Type: application/json" -d '{"message": "<message>", "base64_attachment": "<base64 encoded attachment>", "number": "<number>", "recipients": ["<recipient1>", "<recipient2>"]}' 'http://127.0.0.1:8080/v1/send'```
+
+* Receive messages
+
+  Fetch all new messages in the inbox of the specified number.
+
+   ```curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/receive/<number>'```
+
+   e.g:
+
+   ```curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/receive/+431212131491291'```
+
+* Create a new group
+
+  Create a new group with the specified name and members.  
+
+  ```curl -X POST -H "Content-Type: application/json" -d '{"name": "<group name>", "members": ["<member1>", "<member2>"]}' 'http://127.0.0.1:8080/v1/groups/<number>'``` 
+
+  e.g:
+
+  ```curl -X POST -H "Content-Type: application/json" -d '{"name": "my group", "members": ["+4354546464654", "+4912812812121"]}' 'http://127.0.0.1:8080/v1/groups/+431212131491291'```
+
+* List groups
+
+  ```curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/<number>'```
+
+  e.g:
+
+  ```curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/+431212131491291'```
+
+* Delete a group
+
+  Delete the group with the given group id. The group id can be obtained via the "List groups" REST call. 
+
+  ```curl -X DELETE -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/<number>/<group id>'```
+
+  e.g: 
+
+  ```curl -X DELETE -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/+431212131491291/ckRzaEd4VmRzNnJaASAEsasa'```
+
+* Send a message to a group
+
+  ```curl -X POST -H "Content-Type: application/json" -d '{"message": "Hello World!", "number": "<number>", "recipients": ["<group id>"], "is_group": true}' 'http://127.0.0.1:8080/v1/send'```
+
+  e.g:
+
+  ```curl -X POST -H "Content-Type: application/json" -d '{"message": "Hello World!", "number": "+431212131491291", "recipients": ["ckRzaEd4VmRzNnJaASAEsasa"], "is_group": true}' 'http://127.0.0.1:8080/v1/send'```
+
+In case you need more functionality, please **file a ticket** or **create a PR**
diff --git a/doc/HOMEASSISTANT.md b/doc/HOMEASSISTANT.md
@@ -46,5 +46,33 @@ e.g:
 
 ```curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291/verify/123-456'```
 
+
+## 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.109
+  * 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 Home Assistant `configuration.yaml` file (see [here](https://www.home-assistant.io/integrations/signal_messenger/) for details)
+
 # Troubleshooting
 In case you've problems with the `signal-cli-rest-api` container, have a look [here](TROUBLESHOOTING.md)
diff --git a/publish.sh b/publish.sh
@@ -1,10 +1,11 @@
 #!/bin/bash
 
-while getopts v: option
+while getopts v:t: option
 do
 case "${option}"
 in
 v) VERSION=${OPTARG};;
+t) TAG=${OPTARG};;
 esac
 done
 
@@ -14,8 +15,20 @@ then
 	exit 1
 fi
 
+if [ -z "$TAG" ]
+then
+	echo "Please provide a valid tag with the -t flag. e.g: -t stable (supported tags: dev, stable)"
+	exit 1
+fi
+
+if [[ "$TAG" != "dev" && "$TAG" != "stable" ]]; then
+	echo "Please use either dev or stable as tag"
+	exit 1
+fi
+
 echo "This will upload a new signal-cli-rest-api to dockerhub"
 echo "Version: $VERSION"
+echo "Tag: $TAG"
 echo ""
 
 read -r -p "Are you sure? [y/N] " response
@@ -27,10 +40,18 @@ case "$response" in
 
 		docker buildx create --name multibuilder
 		docker buildx use multibuilder
+
+		if [[ "$TAG" == "stable" ]]; then
+			docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t bbernhard/signal-cli-rest-api:$VERSION . --push
+			docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t bbernhard/signal-cli-rest-api:latest . --push
+        fi
 
-		docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t bbernhard/signal-cli-rest-api:$VERSION . --push
-		docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t bbernhard/signal-cli-rest-api:latest . --push
-        ;;
+		if [[ "$TAG" == "dev" ]]; then
+			docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t bbernhard/signal-cli-rest-api:${VERSION}-dev . --push
+			docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t bbernhard/signal-cli-rest-api:latest-dev . --push
+        fi
+
+		;;
     *)
         echo "Aborting"
 		exit 1