# External API Keys & Account Configuration ("Needs From You")

To run all real-time telephony, speech-to-text, LLM, text-to-speech, and Stripe billing features in production, configure the following environment variables in [`services/call-engine/.env`](file:///c:/wamp64/www/Ai-voice-agent-call-center-project/services/call-engine/.env.example) (a full template is provided in [`services/call-engine/.env.example`](file:///c:/wamp64/www/Ai-voice-agent-call-center-project/services/call-engine/.env.example)):

## 1. Required for Live Voice Calls & Vector RAG
| Variable | Service | Purpose |
| :--- | :--- | :--- |
| `OPENAI_API_KEY` | [OpenAI Platform](https://platform.openai.com) | Powers `gpt-4o-mini` low-latency streaming responses, tool-calling (`check_availability`, `book_appointment`, `lookup_policy`, `escalate_to_human`), Website-to-Agent extraction, Post-Call AI Summaries, and `text-embedding-3-small` vector embeddings for Knowledge Base RAG. *(Ensure active billing/quota on your OpenAI account).* |
| `DEEPGRAM_API_KEY` | [Deepgram Console](https://console.deepgram.com) | Powers `nova-3` real-time streaming STT (`8000Hz mulaw`), `SpeechStarted` VAD barge-in detection, and Deepgram Aura (`aura-asteria-en`) automatic TTS failover. |
| `ELEVENLABS_API_KEY` | [ElevenLabs](https://elevenlabs.io) | Powers ultra-realistic `eleven_turbo_v2_5` (`ulaw_8000`, latency level `4`) streaming voice synthesis. Automatically falls back to Deepgram Aura TTS if quota is exhausted. |
| `ELEVENLABS_VOICE_ID` | ElevenLabs | Default voice ID when a company has not selected a custom voice (default: `21m00Tcm4TlvDq8ikWAM`). |

## 2. Required for PSTN Phone Calls (Twilio)
| Variable | Service | Purpose |
| :--- | :--- | :--- |
| `TWILIO_ACCOUNT_SID` | [Twilio Console](https://console.twilio.com) | Account SID used for outbound test calls (`/api/simulator/outbound-call`) and media stream management. |
| `TWILIO_AUTH_TOKEN` | Twilio Console | Auth token used to validate `X-Twilio-Signature` on `/twilio/*` webhooks and authenticate Twilio REST API calls. |
| `TWILIO_PHONE_NUMBER` | Twilio Console | Default inbound/outbound Twilio phone number in E.164 format (e.g., `+15706308358`). |
| `PUBLIC_WEBHOOK_BASE_URL` | Cloudflare Tunnel / Ngrok / Domain | Your public HTTPS URL pointing to port `3000` of `services/call-engine` (e.g., `https://voice.yourdomain.com`). Set your Twilio number's **A Call Comes In** webhook to `POST https://<PUBLIC_WEBHOOK_BASE_URL>/twilio/inbound-call`. |

## 3. SaaS Billing & Transactional Email (Optional / Production)
| Variable | Service | Purpose |
| :--- | :--- | :--- |
| `STRIPE_SECRET_KEY` | [Stripe Dashboard](https://dashboard.stripe.com/apikeys) | Secret key (`sk_live_...` or `sk_test_...`) enabling live Stripe Checkout session creation on `POST /api/billing/change-plan`. When omitted, plan upgrades apply directly in the database for development/testing. |
| `SMTP_HOST`, `SMTP_USER`, `SMTP_PASS` | Resend / Postmark / Gmail SMTP | Delivers immediate post-call summary & transcript emails to `notificationEmail` after every completed call. |

## 4. Security & Multi-Tenant Admin Bootstrap
| Variable | Purpose |
| :--- | :--- |
| `JWT_SECRET` | High-entropy secret (minimum 32 random bytes) used to sign `HS256` JWT tokens. |
| `DEFAULT_ADMIN_EMAIL` | Initial super-admin email seeded on startup (default: `admin@example.com`). |
| `DEFAULT_ADMIN_PASSWORD` | Initial super-admin password seeded on startup. |
| `ENFORCE_TWILIO_SIGNATURE` | Set to `true` in production to reject any `/twilio/*` request without a valid `X-Twilio-Signature`. |