Providers

Butt-Dial uses a pluggable provider architecture. Every external dependency has an abstract interface, and providers are swappable via environment variables.

Provider Slots

Selection

Set providers via environment variables:

PROVIDER_TELEPHONY=twilio       # twilio | vonage
PROVIDER_EMAIL=resend
PROVIDER_TTS=edge-tts           # edge-tts | elevenlabs | openai
PROVIDER_STT=deepgram
PROVIDER_DATABASE=sqlite        # sqlite | turso | convex
PROVIDER_STORAGE=local          # local | s3 | r2

In demo mode (DEMO_MODE=true), all providers automatically use mock adapters.

Available Adapters

Telephony

• Twilio — Full implementation: SMS, calls, transfers, number management
• Vonage — Full implementation via Nexmo REST APIs
• Mock — Simulated responses for demo/dev

Email

• Resend — Send + domain verification via REST
• Mock — Simulated responses

TTS (Text-to-Speech)

• Edge TTS — Free Microsoft TTS, no API key needed (default)
• ElevenLabs — Premium voices via API
• OpenAI — OpenAI TTS via /v1/audio/speech
• Mock — Returns silent WAV

STT (Speech-to-Text)

• Deepgram — HTTP POST to /v1/listen
• Mock — Returns fixed transcription

Database

• SQLite — Local file, zero setup (development default)
• Turso — libSQL HTTP pipeline
• Convex — REST-based (stub)

Storage

• Local — Filesystem + Express static route (development default)
• S3 — AWS S3 with Signature V4
• R2 — Cloudflare R2 (wraps S3 adapter)

Provider Interfaces

Core tools call interfaces, never vendor-specific code:

// ITelephonyProvider
sendSms(params: { from, to, body }): Promise<{ messageId, status, cost }>
makeCall(params: { from, to, webhookUrl }): Promise<{ callSid, status }>
transferCall(params: { callSid, to }): Promise<{ status }>
buyNumber(params: { country }): Promise<{ phoneNumber, sid }>
releaseNumber(sid: string): Promise<void>

// IEmailProvider
send(params: { from, to, subject, body }): Promise<{ messageId, status, cost }>

// ITTSProvider
synthesize(text: string, options?): Promise<{ audio: Buffer, durationMs }>

// IStorageProvider
upload(key, data, contentType): Promise<{ url, key }>
download(key): Promise<Buffer>
delete(key): Promise<void>

Alternative Providers (Not Yet Implemented)

The following providers can be added as adapters. Each implements the same interface as existing adapters.

Telephony Alternatives

Email Alternatives

WhatsApp Alternatives

TTS Alternatives

STT Alternatives

Database Alternatives

Storage Alternatives

Adding a New Provider

1. Create adapter file in src/providers/ (e.g., telephony-plivo.ts)
2. Implement the relevant interface
3. Add selection logic in src/providers/factory.ts
4. Add config fields in src/lib/config.ts
5. Add to comms_register_provider enum