AI Calling Architecture (Twilio + OpenAI + ElevenLabs + WhatsApp)

This project now follows the architecture you shared:

Student Phone -> Twilio -> Node.js Backend -> (OpenAI + ElevenLabs + State Machine) -> Optional MongoDB -> WhatsApp follow-up

Components implemented

• Call layer (Twilio): outbound trigger via GET /call, call status webhooks via POST /call-status
• Logic flow (state machine): intro -> branch -> admission -> counselling -> whatsapp -> closing
• AI brain (OpenAI): per-turn decisioning (assistantText, nextState, endCall, sendWhatsapp)
• Voice engine (ElevenLabs): dynamic MP3 generated per turn and played to caller
• Optional DB (MongoDB): conversation + transcript + state + status persistence
• WhatsApp follow-up: Twilio WhatsApp message on call completion

Environment variables

Required:

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER
• PUBLIC_BASE_URL (public HTTPS URL, usually ngrok)

Mode selection:

• MODE=pre_generated (recommended trial mode, plays fixed MP3 files)
• MODE=live_ai (dynamic OpenAI + ElevenLabs per turn)

AI + voice:

• USE_AI=true
• OPENAI_API_KEY
• OPENAI_MODEL=gpt-4.1-mini (or another chat model)
• ELEVENLABS_API_KEY
• ELEVENLABS_VOICE_ID
• ELEVENLABS_SPEED=0.9 (optional, lower = slower, default 0.9)

WhatsApp follow-up:

• TWILIO_WHATSAPP_FROM=whatsapp:+14155238886 (or your approved sender)
• WHATSAPP_FOLLOWUP_TEMPLATE=... (optional custom text)

Optional MongoDB:

• MONGODB_URI=mongodb+srv://...
• MONGODB_DB_NAME=ai_call_demo (optional)

Routes

• GET / -> health + architecture info
• GET /call?to=9876543210 -> start outbound call
• POST /voice -> first AI prompt
• POST /voice/turn -> next turns (<Gather input="speech">)
• POST /call-status -> status callback from Twilio
• GET /audio/* -> generated MP3 hosting

Required MP3 files (MODE=pre_generated)

Place all files under public/audio/ with exact names:

• welcome.mp3
• time.mp3
• branch.mp3
• cse_intro.mp3
• cse_scope.mp3
• college.mp3
• admission.mp3
• counselling.mp3
• whatsapp.mp3
• closing.mp3
• fallback.mp3

Suggested script per file:

• welcome.mp3
  नमस्कार 😊 मी संजीवन कॉलेज, पन्हाळा येथून बोलत आहे.
  मी रोहन सरांशी बोलतोय का?

• time.mp3
  धन्यवाद. तुम्ही आमच्या कॉलेजमध्ये अ‍ॅडमिशन संदर्भात इन्क्वायरी केली होती म्हणून कॉल केला आहे.
  २ मिनिटं बोलायला वेळ आहे का?

• branch.mp3
  छान 👍 तुम्हाला कोणत्या ब्रँचमध्ये अ‍ॅडमिशन घ्यायचं आहे?

• cse_intro.mp3
  खूप छान निवड आहे 👌
  Computer Science Engineering ही आजच्या काळातील सर्वात जास्त डिमांड असलेली शाखा आहे.

• cse_scope.mp3
  मी तुम्हाला सोप्या भाषेत सांगतो —
  CSE केल्यावर तुमच्यासाठी Software Developer,
  AI किंवा Machine Learning Engineer,
  Data Scientist,
  Cyber Security Expert,
  Cloud Engineer,
  Web आणि App Developer अशा संधी उपलब्ध होतात.
  आज प्रत्येक क्षेत्र IT वर चालतंय — बँक, हॉस्पिटल, सरकार, उद्योग, सगळीकडे.
  पुढच्या 10 ते 15 वर्षांत AI आणि Automation मुळे CSE ची मागणी अजून वाढणार आहे.
  फ्रेशर सॅलरी साधारण 4 ते 10 लाख per year पासून सुरू होते आणि अनुभवाने खूप वाढते.

• college.mp3
  आमच्या कॉलेजमध्ये CSE विद्यार्थ्यांसाठी खास सुविधा आहेत.
  AI आणि Machine Learning वर फोकस,
  पहिल्या वर्षापासून Placement Training,
  Coding आणि Internship Support,
  Hostel आणि Transportation सुविधा.

• admission.mp3
  तुम्ही यावर्षीच अ‍ॅडमिशन घेण्याचा विचार करत आहात का?

• counselling.mp3
  छान 😊 सध्या आम्ही Free Admission Counselling देत आहोत.
  तुम्हाला कॉलेजला भेट द्यायची आहे का
  किंवा Online Counselling घ्यायची आहे?

• whatsapp.mp3
  नक्की 👍 मी लगेच तुम्हाला WhatsApp वर खालील माहिती पाठवतो:
  Fees Structure,
  Required Documents,
  आणि Admission Process.
  हा नंबर WhatsApp वर आहे ना?

• closing.mp3
  खूप धन्यवाद 😊
  लवकरच तुमची भेट होईल अशी आशा आहे.
  तुमचा दिवस शुभ जावो!

• fallback.mp3
  Sorry, awaz neet ala nahi. Krupaya punha sanga.

Run

npm install
npm start

Expose your app publicly:

ngrok http 3000

Set ngrok HTTPS URL in PUBLIC_BASE_URL.

Trigger call:

• GET /call?to=9876543210
• or GET /call?to=%2B919876543210

Notes

• In pre_generated mode, runtime OpenAI and ElevenLabs calls are skipped.
• Place your pre-generated files in public/audio/: welcome.mp3, time.mp3, branch.mp3, cse_intro.mp3, cse_scope.mp3, college.mp3, admission.mp3, counselling.mp3, whatsapp.mp3, closing.mp3, fallback.mp3.
• If ElevenLabs keys are missing or generation fails, the app automatically falls back to Twilio Say.
• If MongoDB is not configured, the app runs with in-memory session state only.
• Ensure Twilio Voice webhook points to your public /voice URL if you trigger calls from Twilio console.