Signal

This step happens entirely outside of Bubble and must be completed before any Bubble configuration. You need a Linux VPS with Docker and Docker Compose installed. SSH into your VPS and create a directory for the relay: ``` mkdir -p ~/signal-relay && cd ~/signal-relay ``` Create a `docker-compose.yml` file with the following content: ```yaml version: '3' services: signal-cli-rest-api: image: bbernhard/signal-cli-rest-api:latest ports: - '8080:8080' volumes: - './signal-cli-config:/home/.local/share/signal-cli' environment: - MODE=json-rpc restart: unless-stopped ``` The `./signal-cli-config` volume is critical — it stores your Signal registration keys. If this directory is lost, your Signal number loses its registration and must be re-verified. Start the relay: ``` docker compose up -d ``` Verify it is running: ``` docker compose logs -f ``` You should see the relay starting up without errors. The API is now accessible at `http://localhost:8080` on the VPS. In the next step, you will register a phone number. Do not expose port 8080 to the internet without authentication — set up a reverse proxy with Basic Auth and HTTPS first (Step 3).

1version: '3'
2services:
3  signal-cli-rest-api:
4    image: bbernhard/signal-cli-rest-api:latest
5    ports:
6      - '8080:8080'
7    volumes:
8      - './signal-cli-config:/home/.local/share/signal-cli'
9    environment:
10      - MODE=json-rpc
11    restart: unless-stopped

Signal requires every number to be verified via SMS (or voice call) before it can send or receive messages. This registration step is done via CLI commands or curl requests to the relay's local API — it cannot be done from Bubble. This is a one-time manual setup per phone number. From inside the VPS (while the relay container is running), request a verification SMS to your chosen phone number in E.164 format. Replace `+15551234567` with your actual number: ``` curl -X POST 'http://localhost:8080/v1/register/+15551234567' ``` Your phone (or VoIP number dashboard) will receive a 6-digit SMS code. Submit the code to complete registration: ``` curl -X POST 'http://localhost:8080/v1/register/+15551234567/verify/123456' ``` Set a profile name for the Signal account (required for some features): ``` curl -X PUT 'http://localhost:8080/v1/profiles/+15551234567' \ -H 'Content-Type: application/json' \ -d '{"name": "Bubble Alerts Bot"}' ``` Verify registration by listing accounts: ``` curl 'http://localhost:8080/v1/accounts' ``` You should see your number listed. The relay's `signal-cli-config` directory now contains the Signal protocol keys for this number — this is what needs to be backed up. **Important:** The phone number you register must NOT be actively in use as a personal Signal account on another device. If a number is registered on a Signal app, registering it on the relay will unregister it from your phone.

1# Step 1: Request verification SMS
2curl -X POST 'http://localhost:8080/v1/register/+15551234567'
3
4# Step 2: Verify with the code received via SMS (replace 123456)
5curl -X POST 'http://localhost:8080/v1/register/+15551234567/verify/123456'
6
7# Step 3: Set a profile name
8curl -X PUT 'http://localhost:8080/v1/profiles/+15551234567' \
9  -H 'Content-Type: application/json' \
10  -d '{"name": "Bubble Alerts Bot"}'
11
12# Step 4: Verify registration
13curl 'http://localhost:8080/v1/accounts'

Bubble's API Connector requires HTTPS endpoints and will reject self-signed certificates. You also need to protect the relay behind authentication so that only your Bubble app (and you) can use it. This is done with an nginx reverse proxy providing both TLS and Basic Auth. Install nginx and certbot on your VPS: ``` sudo apt update && sudo apt install -y nginx certbot python3-certbot-nginx apache2-utils ``` Create a Basic Auth password file (replace `bubbleuser` and choose a strong password): ``` sudo htpasswd -c /etc/nginx/.htpasswd bubbleuser ``` Create an nginx config at `/etc/nginx/sites-available/signal-relay`: ```nginx server { listen 80; server_name signal-relay.yourdomain.com; location / { auth_basic "Signal Relay"; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ``` Enable the site and get a Let's Encrypt certificate: ``` sudo ln -s /etc/nginx/sites-available/signal-relay /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx sudo certbot --nginx -d signal-relay.yourdomain.com ``` Certbot will automatically configure HTTPS. Your relay is now accessible at `https://signal-relay.yourdomain.com` with Basic Auth protection. Alternatively, if you prefer not to manage nginx, **Cloudflare Tunnel** (free tier) can provide HTTPS and access control without managing TLS certificates manually — point the tunnel to `http://localhost:8080` and add Cloudflare Access rules for IP allowlisting.

1# nginx reverse proxy configuration
2server {
3    listen 80;
4    server_name signal-relay.yourdomain.com;
5
6    location / {
7        auth_basic "Signal Relay";
8        auth_basic_user_file /etc/nginx/.htpasswd;
9        proxy_pass http://localhost:8080;
10        proxy_set_header Host $host;
11        proxy_set_header X-Real-IP $remote_addr;
12    }
13}

Now that your relay is running with HTTPS and Basic Auth, you can configure Bubble's API Connector to connect to it. In your Bubble editor, go to the **Plugins** tab → **Add plugins** → search for **'API Connector'** (by Bubble) → **Install**. Click on the API Connector in your plugins list and click **Add another API**. Name it `Signal Relay`. In the **Base URL** field, enter your relay's domain: `https://signal-relay.yourdomain.com`. Check the **Private** checkbox next to the Base URL. In the **Shared headers** section, add: - Key: `Content-Type`, Value: `application/json`, Private: unchecked For **Authentication**: select **Basic auth**. Enter your nginx htpasswd username in the Username field and the password in the Password field. Check **Private** on both. Now add the send message call: click **Add a call**. Name it `Send Signal Message`. Set method to **POST**. Set the endpoint path to `/v1/send`. Set **Body type** to **JSON**. In the body, add: ```json { "message": "<dynamic:message_text>", "number": "+15551234567", "recipients": ["<dynamic:recipient_number>"] } ``` Replace `+15551234567` with your registered sender number (this can be hardcoded as a constant since you only have one relay number). Mark `message_text` and `recipient_number` as dynamic text parameters. Set **Use as** to **Action**. Click **Initialize call**. In the parameter fields, enter a real test message and a recipient phone number you control (in E.164 format, e.g. `+15559876543`). Click **Send**. A successful response returns HTTP 201 or 200 with an empty body or a messageId. Check the recipient's Signal app — the message should arrive within seconds. If you see 'There was an issue setting up your call', verify the relay URL is correct, your Basic Auth credentials match the htpasswd file, and the relay container is still running.

1{
2  "api_name": "Signal Relay",
3  "base_url": "https://signal-relay.yourdomain.com",
4  "authentication": "Basic Auth",
5  "username": "<relay username — Private>",
6  "password": "<relay password — Private>",
7  "shared_headers": [
8    { "key": "Content-Type", "value": "application/json" }
9  ],
10  "call_name": "Send Signal Message",
11  "method": "POST",
12  "endpoint": "/v1/send",
13  "body": {
14    "message": "<dynamic:message_text>",
15    "number": "+15551234567",
16    "recipients": ["<dynamic:recipient_number>"]
17  }
18}

With the API Connector configured, wire it into your Bubble app logic using a Backend Workflow. Backend Workflows are required for this integration on a paid Bubble plan — they keep the relay credentials server-side and allow you to trigger alerts from database events, scheduled jobs, and other server-side triggers. Go to the **Backend Workflows** section (left sidebar under Workflow, or the Server-side actions area depending on your Bubble plan). Click **New API Workflow** and name it `Send Signal Alert`. This workflow should accept parameters: - `message` (text) — the alert message content - `recipient` (text) — the recipient phone number in E.164 format Add an action: **Plugins → Signal Relay - Send Signal Message**. Set: - `message_text` → this workflow's `message` parameter - `recipient_number` → this workflow's `recipient` parameter Optionally, add a second action to log the alert: **Data (Things) → Create a new Signal_Log** (create this data type with fields: recipient text, message text, sent_at date, status text). This audit log is valuable for debugging and for tracking alert delivery. Save the Backend Workflow. Now trigger it from anywhere in your app. From a client-side workflow (button click, condition met), add a **Schedule API Workflow** action pointing to `Send Signal Alert`. Pass the recipient number from your database (e.g., a User's phone field) and a dynamic message text (e.g., `'Alert: ' + triggering_record's details`). For automated alerts without a user action, use Bubble's **Recurring Backend Workflow** or trigger the Backend Workflow from a data condition. For example: when a new Error_Log record is created with severity = 'Critical', run the Send Signal Alert workflow. RapidDev's team has helped founders build advanced notification pipelines in Bubble with encrypted messaging, escalation logic, and multi-channel fallbacks — if you need help architecting a resilient alert system, a free scoping call is available at rapidevelopers.com/contact.

The Signal relay requires ongoing maintenance that other API integrations do not. Unlike rotating an API key, losing the relay's data volume means a full re-registration — including getting a new SMS verification code for your Signal number and potentially losing group memberships. **Backups**: Set up an automated daily backup of the `./signal-cli-config` directory on your VPS. A simple cron job can compress and upload it to a cloud bucket: ```bash 0 3 * * * tar -czf /backup/signal-config-$(date +%Y%m%d).tar.gz ~/signal-relay/signal-cli-config && rclone copy /backup/ s3:your-bucket/signal-backup/ ``` **Relay updates**: The signal-cli-rest-api project releases updates to track Signal protocol changes. When Signal updates its protocol, older relay versions may stop working. Watch the project's GitHub releases and update the Docker image periodically: ```bash docker compose pull && docker compose up -d ``` **Monitoring**: Add a health check to your Bubble app — a scheduled Backend Workflow that calls `GET /v1/accounts` on the relay every few hours. If the call fails or returns an error, send an alert to yourself (email or another channel) so you know the relay is down before it causes missed notifications. **Volume awareness**: Each Signal message sent from Bubble = one API Connector call action + one database write for the log = approximately 2 Workload Units. At low message volumes (under 100 messages/day), this is negligible. Bubble's WU consumption is not a concern for the typical use case of this integration. **Privacy rules**: If you store Signal alert content in a Bubble data type (Signal_Log), apply privacy rules under **Data → Privacy** to restrict log reads to admin users only. Alert message content may be sensitive — do not leave it readable by all users by default.

1# Automated backup cron job (add to VPS crontab with: crontab -e)
2# Runs daily at 3am, compresses config, uploads to cloud storage
30 3 * * * tar -czf /tmp/signal-config-$(date +%Y%m%d).tar.gz ~/signal-relay/signal-cli-config
4
5# Relay update command (run manually or add to scheduled maintenance)
6cd ~/signal-relay && docker compose pull && docker compose up -d
7
8# Health check (test relay is responding)
9curl -u bubbleuser:yourpassword https://signal-relay.yourdomain.com/v1/accounts