External Services Setup

Configure WhatsApp, Signal, Email, CalDAV/CardDAV, OpenAI, and Brave Search integrations

Messenger Selection

PiSovereign supports one messenger at a time:

messenger = "signal"     # Signal via signal-cli (default)
messenger = "whatsapp"   # WhatsApp Business API
messenger = "none"       # Disable messenger integration

WhatsApp Business

PiSovereign uses the WhatsApp Business API for bidirectional messaging.

Meta Business Account

1. Create a Meta Business Account
2. Create a Meta Developer Account

WhatsApp App Setup

1. Create an app at developers.facebook.com/apps (type: Business)
2. Add the WhatsApp product
3. In WhatsApp → Getting Started, note the Phone Number ID and generate an Access Token
4. For a permanent token: Business Settings → System Users → create Admin → generate token with whatsapp_business_messaging permission
5. Note the App Secret from App Settings → Basic

Webhook Configuration

PiSovereign needs a public URL for WhatsApp webhooks. The Docker Compose stack uses Traefik for this automatically.

Configure in Meta Developer Console:

1. WhatsApp → Configuration → Edit Webhooks
2. Callback URL: https://your-domain.com/v1/webhooks/whatsapp
3. Verify Token: your chosen verify_token
4. Subscribe to: messages, message_template_status_update

PiSovereign Configuration

Store credentials in Vault:

docker compose exec vault vault kv put secret/pisovereign/whatsapp \
    access_token="your-access-token" \
    app_secret="your-app-secret"

Add to config.toml:

[whatsapp]
phone_number_id = "your-phone-number-id"
verify_token = "your-verify-token"
signature_required = true
api_version = "v18.0"

Signal Messenger

Signal provides privacy-focused messaging with end-to-end encryption, polling-based delivery (no public URL required), and voice message support.

For the full setup guide, see Signal Setup.

Quick config:

messenger = "signal"

[signal]
phone_number = "+1234567890"
socket_path = "/var/run/signal-cli/socket"

Email Integration (IMAP/SMTP)

PiSovereign supports any provider with standard IMAP/SMTP access. Use the provider field for automatic host/port configuration, or specify hosts and ports manually.

Provider Quick Reference

Gmail: Enable IMAP in Gmail settings, then generate an App Password (requires 2-Step Verification).

Outlook: Enable IMAP in settings, generate an App Password at account.microsoft.com/security if 2FA is enabled.

Proton Mail: Requires Proton Bridge running on the host. Use the Bridge Password shown in Bridge UI — not your Proton account password. Set verify_certificates = false since Bridge uses self-signed certs.

Configuration

Store the password in Vault:

docker compose exec vault vault kv put secret/pisovereign/email \
    password="your-email-password"

Example configs — choose one:

# Gmail (using provider preset)
[email]
provider = "gmail"
email = "yourname@gmail.com"

# Proton Mail (default provider — via Bridge)
[email]
provider = "proton"
email = "yourname@proton.me"
[email.tls]
verify_certificates = false

# Outlook (custom provider with explicit hosts)
[email]
provider = "custom"
imap_host = "outlook.office365.com"
imap_port = 993
smtp_host = "smtp.office365.com"
smtp_port = 587
email = "yourname@outlook.com"

Migration note: The config section was previously named [proton]. The old name still works but [email] is the canonical name going forward.

CalDAV / CardDAV (Baïkal)

Baïkal is a lightweight, self-hosted CalDAV/CardDAV server included in the Docker Compose stack as an optional profile.

Docker Setup

docker compose --profile caldav up -d

This starts Baïkal at http://localhost/caldav (via Traefik). PiSovereign accesses it internally via the Docker network at http://baikal:80/dav.php.

Security: Baïkal is not directly exposed to the internet. All access is through the Docker network or localhost.

Auto-recreation: PiSovereign automatically re-creates calendars and address books if they return 404 errors (e.g., after a Baïkal database reset or re-initialization). No manual intervention is needed.

Initial Setup

1. Open http://localhost/caldav in your browser
2. Complete the setup wizard, set an admin password, choose SQLite
3. Create a user under Users and Resources
4. Create a calendar via any CalDAV client or the admin interface

Configuration

Store credentials in Vault (optional):

docker compose exec vault vault kv put secret/pisovereign/caldav \
    username="your-username" \
    password="your-password"

Add to config.toml:

[caldav]
server_url = "http://baikal:80/dav.php"
username = "your-username"
password = "your-password"
calendar_path = "/calendars/username/default/"
verify_certs = true
timeout_secs = 30

CardDAV for contacts uses the same server and credentials — PiSovereign automatically discovers the address book.

OpenAI API

OpenAI is used as an optional cloud fallback for speech processing (STT/TTS).

Setup

1. Create an account at platform.openai.com
2. Add a payment method and set usage limits (recommended: $10–20/month)
3. Create an API key at platform.openai.com/api-keys

Store in Vault:

docker compose exec vault vault kv put secret/pisovereign/openai \
    api_key="sk-your-openai-key"

Configuration

[speech]
provider = "hybrid"  # Local first, OpenAI fallback

openai_base_url = "https://api.openai.com/v1"
stt_model = "whisper-1"
tts_model = "tts-1"
default_voice = "nova"
timeout_ms = 60000

[speech.hybrid]
prefer_local = true
allow_cloud_fallback = true

For maximum privacy (no cloud at all):

[speech]
provider = "local"

[speech.hybrid]
prefer_local = true
allow_cloud_fallback = false

Brave Search API

Brave Search enables web search with source citations. DuckDuckGo is used as an automatic fallback.

Setup

1. Sign up at brave.com/search/api — the Free tier (2,000 queries/month) is sufficient for personal use
2. Create an API key in the dashboard

Store in Vault:

docker compose exec vault vault kv put secret/pisovereign/websearch \
    brave_api_key="BSA-your-brave-api-key"

Configuration

[websearch]
api_key = "BSA-your-brave-api-key"
max_results = 5
timeout_secs = 30
fallback_enabled = true
safe_search = "moderate"
country = "DE"
language = "de"

DuckDuckGo’s Instant Answer API is used automatically when Brave is unavailable, rate-limited, or not configured. No API key required. To disable the fallback:

[websearch]
fallback_enabled = false

Verify All Integrations

# Check all services
docker compose exec pisovereign pisovereign-cli status

# Or via HTTP
curl https://your-domain.example.com/ready/all | jq

Troubleshooting

WhatsApp webhook not receiving messages

• Verify callback URL is publicly accessible
• Check verify_token matches between config and Meta console
• Ensure webhook is subscribed to messages

Email connection refused

• Verify host and port match your provider
• For Proton: ensure Bridge is running on the host
• Check password type (App Password for Gmail/Outlook, Bridge Password for Proton)

CalDAV authentication failed

• Verify username/password
• Check calendar_path format — must match user and calendar name in Baïkal

Next Steps

• Configuration Reference — Fine-tune all options
• Monitoring — Track service health