integrations/, strictly decoupled from application database queries and business logic.
The 5 Integration Channels
Phone Carriers (PSTN)
Connect Vobiz, Exotel, Twilio, or Telnyx to place live telephone calls for autonomous AI voice campaigns and mobile auto-dialers.
AI Voice Platforms
Connect Vapi, Retell AI, ElevenLabs, Sarvam AI, Bolna, LiveKit, OpenAI Realtime, or Pipecat as the conversational intelligence engine.
WhatsApp (Meta Cloud API)
Direct integration with the Meta WhatsApp Cloud API for official template broadcasts, interactive quick-reply buttons, and team inbox dialogues.
SMS Gateways
Connect Twilio, Gupshup, Sinch, AWS SNS, Plivo, Telnyx, Vonage, Infobip, or Bird for high-throughput promotional SMS and two-way conversations.
Email Service Providers
Connect AWS SES, SendGrid, Brevo, Mailchimp, Mailgun, Gmail, Outlook, or Constant Contact for bulk broadcasts and direct threaded email management.
Architectural Dispatch Flow
Every integration channel follows an asynchronous, audited dispatch lifecycle that isolates external network calls from the main NestJS API request thread:Integration Governance Laws
The BrokerOS monorepo enforces strict architectural laws across all packages inintegrations/:
1. In-App UI Configuration & Zero Credential Hardcoding
Never embed tokens, API keys, client secrets, or webhook signing keys inside application source code. Administrators configure credentials directly within the BrokerOS web UI under Dashboard -> Marketing -> [Channel] -> Settings. Credentials are encrypted using AES-256-GCM and stored in PostgreSQL (MarketingIntegration, SmsIntegration, VoiceTelephonyIntegration, VoiceAgentIntegration). Adapters receive credentials dynamically via configuration objects passed from the caller (apps/api or apps/workers). The repository root .env serves strictly as an optional developer fallback during local testing.
2. Adapter Purity (No Database Access)
Adapters only handle request preparation, HTTP transport, retries, timeouts, cryptographic signing, error normalization, and response parsing. Never import database models or@brokeros/prisma inside integrations/.
3. No Direct External Calls from Applications
Application modules (apps/api and apps/workers) must never make raw fetch() or axios calls directly to external SaaS providers. All external calls must route through typed functions exported from @brokeros/int-* workspace packages.
4. Standard Adapter Interface Contract
Every delivery adapter implements a consistent TypeScript interface:send(payload, credentials): Transmits the message or call and returns a normalized result.validateConfig(credentials): Verifies that API keys or SIP parameters are valid before saving.verifyWebhookSignature(headers, body, secret): Validates incoming webhook authenticity using HMAC signatures.
Security Model: Storage & Webhook Verification
BrokerOS protects third-party credentials and communication channels using enterprise cryptographic standards:- At-Rest Secret Encryption: All sensitive credentials (API tokens, Twilio Auth Tokens, Exotel keys, Meta access tokens, and SIP passwords) are encrypted using AES-256-GCM with a dynamic initialization vector (IV) before persistence.
- In-Transit Webhook Integrity: Inbound callbacks from external providers are cryptographically validated using HMAC-SHA256 signatures (such as Meta
X-Hub-Signature-256, Twilio signature headers, and Retell signature tokens) to prevent payload spoofing. - Zero Logging Policy: Authentication headers, raw API keys, and decrypted credentials are strictly scrubbed from application logging pipelines.