Debian Codegraph @

docs/services/chat/signal/index.md

raw
1 # Signal
2
3 ## URL Format
4
5 !!! info ""
6 signal://[__`user`__[:__`password`__]@]__`host`__[:__`port`__]/__`source_phone`__/__`recipient1`__[,__`recipient2`__,...]
7
8 ## Setting up Signal API Server
9
10 Signal notifications require a Signal API server that can send messages on behalf of a registered Signal account. These implementations are built on top of __[signal-cli](https://github.com/AsamK/signal-cli)__, the unofficial command-line interface for Signal (3.8k+ stars).
11
12 Popular open-source implementations include:
13
14 - __[signal-cli-rest-api](https://github.com/bbernhard/signal-cli-rest-api)__: Dockerized REST API wrapper for signal-cli (2.1k+ stars)
15 - __[secured-signal-api](https://github.com/codeshelldev/secured-signal-api)__: Security proxy for signal-cli-rest-api with authentication and access control
16
17 Common setup involves:
18
19 1. __Phone Number__: A dedicated phone number registered with Signal
20 2. __API Server__: A server running signal-cli with REST API capabilities
21 3. __Account Linking__: Linking the server as a secondary device to your Signal account
22 4. __Optional Security Layer__: Authentication and endpoint restrictions via a proxy
23
24 The server must be able to receive SMS verification codes during initial setup and maintain a persistent connection to Signal's servers.
25
26 !!! tip "Setup Resources"
27 See the [signal-cli-rest-api documentation](https://github.com/bbernhard/signal-cli-rest-api) and [secured-signal-api documentation](https://github.com/codeshelldev/secured-signal-api) for detailed setup instructions.
28
29 ## URL Parameters
30
31 ### Host and Port
32
33 - `host`: The hostname or IP address of your Signal API server (default: localhost)
34 - `port`: The port number (default: 8080)
35
36 ### Authentication
37
38 The Signal service supports multiple authentication methods:
39
40 - `user`: Username for HTTP Basic Authentication (optional)
41 - `password`: Password for HTTP Basic Authentication (optional)
42 - `token` or `apikey`: API token for Bearer authentication (optional)
43
44 !!! tip "Authentication Priority"
45 If both token and user/password are provided, the API token takes precedence and uses Bearer authentication. This is useful for [secured-signal-api](https://github.com/codeshelldev/secured-signal-api) which prefers Bearer tokens.
46
47 ### Source Phone Number
48
49 The `source_phone` is your Signal phone number with country code (e.g., +1234567890) that is registered with the API server.
50
51 ### Recipients
52
53 Recipients can be:
54
55 - __Phone numbers__: With country code (e.g., +0987654321)
56 - __Group IDs__: In the format `group.groupId`
57
58 ### TLS Configuration
59
60 - Use `signal://` for HTTPS (default, recommended)
61 - Use `signal://...?disabletls=yes` for HTTP (insecure, for local testing only)
62
63 ## Examples
64
65 ### Send to a single phone number
66
67 ```
68 signal://localhost:8080/+1234567890/+0987654321
69 ```
70
71 ### Send to multiple recipients
72
73 ```
74 signal://localhost:8080/+1234567890/+0987654321/+1123456789/group.testgroup
75 ```
76
77 ### Send to a group
78
79 ```
80 signal://localhost:8080/+1234567890/group.abcdefghijklmnop=
81 ```
82
83 ### With authentication
84
85 ```
86 signal://user:password@localhost:8080/+1234567890/+0987654321
87 ```
88
89 ### With API token (Bearer auth)
90
91 ```
92 signal://localhost:8080/+1234567890/+0987654321?token=YOUR_API_TOKEN
93 ```
94
95 ### Using HTTP instead of HTTPS
96
97 ```
98 signal://localhost:8080/+1234567890/+0987654321?disabletls=yes
99 ```
100
101 ## Attachments
102
103 The Signal service supports sending base64-encoded attachments. Use the `attachments` parameter with comma-separated base64 data:
104
105 ```bash
106 # Send with attachments via CLI
107 shoutrrr send "signal://localhost:8080/+1234567890/+0987654321" \
108 "Message with attachment" \
109 --attachments "base64data1,base64data2"
110 ```
111
112 !!! note "Attachment Format"
113 Attachments must be provided as base64-encoded data. The API server handles the MIME type detection and file handling.
114
115 ## Optional Parameters
116
117 You can specify additional parameters in the URL query string:
118
119 - `disabletls=yes`: Force HTTP instead of HTTPS (same as using `signals://`)
120
121 ## Implementation Notes
122
123 The Signal service sends messages using HTTP POST requests to the API server's send endpoint with JSON payloads containing the message, source number, and recipient list. The server handles the actual Signal protocol communication.