Integrations — Overview¶
Audience: Business stakeholders, product owners, analysts, new team members.
What This Module Does¶
The Integrations module is how Swisper connects to external services. Without it, Swisper would be limited to general conversation — it couldn't read emails, check calendars, send notifications, or access financial data. Each integration follows its own connection flow (OAuth, verification code, or API key), but once connected, the integration works transparently: the user simply asks Swisper to check their email or schedule a meeting, and the correct provider is used automatically.
The module manages five integrations across three categories:
| Category | Integration | Connection Method |
|---|---|---|
| Email & Calendar | Gmail | OAuth 2.0 (Google) |
| Email & Calendar | Office 365 | OAuth 2.0 (Microsoft) |
| Notification Channel | Telegram | 4-digit verification code via bot |
| Notification Channel | Threema | Direct Threema ID entry |
| Data Integration | WealthOS | API key |
Who It Serves¶
| Persona | Need |
|---|---|
| End users | Connect their email, calendar, and messaging accounts so Swisper can act on their behalf — reading emails, scheduling meetings, and sending notifications |
| Product owners | Understanding which services are supported, how connections are established, and what data flows through each integration |
| Support staff | Diagnosing connection issues — why an OAuth token expired, why Telegram verification failed, or why a user's email isn't syncing |
Key Capabilities¶
- OAuth-based email/calendar — Gmail and Office 365 connections via standard OAuth 2.0 with automatic token refresh. Scopes include email read/write, calendar access, and contact reading.
- Multi-provider support — Users can connect both Gmail and Office 365 simultaneously. One is marked as the default provider for sending; the other remains available for reading.
- Encrypted credential storage — All tokens, API keys, and configuration values are encrypted at rest using PGPString (PostgreSQL PGP encryption).
- Email signature management — Users can store and manage per-account email signatures (HTML), which the productivity agent uses when composing emails.
- Telegram bot verification — A 4-digit code flow where the user sends the code to the Swisper Telegram bot, which links their chat to their account for proactive notifications.
- Threema one-way messaging — Users provide their Threema ID; the system uses the Threema Gateway for outbound notifications without requiring a verification handshake.
- Unified status API — A single endpoint (
GET /integrations/status) returns the connection state of all integrations, used by the frontend to show connected/disconnected badges.
How It Fits in the Platform¶
- Productivity Agent — Uses stored OAuth tokens to access Gmail and Office 365 APIs for email management, calendar operations, and contact resolution.
- Background Jobs — Email ingestion, calendar sync, and email classification jobs use stored tokens to periodically fetch new data from connected providers.
- Signals & Notifications — Telegram and Threema integrations are the delivery channels for proactive notifications (daily briefings, email alerts, meeting prep).
- Wealth Agent — Uses the stored WealthOS API key to query client portfolios, holdings, and transactions.
- Frontend — The integrations settings page shows connection status, allows connecting/disconnecting, and manages email signatures.
Limits and Edge Cases¶
- One token per provider per user. A user can have one Gmail and one Office 365 connection. Reconnecting replaces the existing token via upsert.
- Token expiry. OAuth tokens expire and are refreshed automatically by the provider adapters. If a refresh token is revoked (user changed Google password, admin revoked access), the integration silently fails until the user reconnects.
- Telegram requires bot interaction. The user must message the Swisper Telegram bot with the verification code. If the bot is unreachable or the code expires, verification fails.
- Threema is one-way. The Threema Gateway only supports outbound messages. Users cannot reply to Swisper via Threema.
- No webhook-based sync. Email and calendar data are fetched via polling (background jobs), not push notifications. There is a delay between when an email arrives and when Swisper knows about it.
FAQ¶
Q: Can I connect both Gmail and Office 365 at the same time? A: Yes. Both can be connected simultaneously. One is marked as the default for sending emails; the other is still used for reading and calendar operations.
Q: What happens if my Google password changes? A: The OAuth refresh token may be invalidated. Swisper will fail to access your email until you reconnect via the integrations settings page.
Q: How does Telegram verification work? A: You click "Connect Telegram" in settings, which generates a 4-digit code. You send this code to the @swisper_bot on Telegram. The backend verifies the code and links your Telegram chat to your Swisper account.
Q: Is my API key / OAuth token stored securely? A: Yes. All credentials are encrypted at rest using PostgreSQL PGP encryption (PGPString). They are never stored in plaintext.
Q: Can I receive notifications on both Telegram and Threema? A: Yes. Each notification channel can be enabled or disabled independently via the notification preferences settings.