This repository contains the advanced codebase for a WhatsApp survey bot, leveraging FastAPI, Firebase, Twilio, and OpenAI. The bot is expertly designed to conduct structured and engaging surveys over WhatsApp, collecting valuable insights on community and personal issues directly from users.
- Firebase Integration: Manages user interaction history and session data effectively.
- Twilio WhatsApp API: Enables robust sending and receiving of WhatsApp messages.
- OpenAI API: Utilizes cutting-edge AI to deliver engaging, contextually appropriate responses.
- FastAPI Framework: Offers a scalable and efficient backend, ideal for real-time applications.
- Python 3.8+
- Firebase account with a service account key
- Twilio account with WhatsApp capabilities
- OpenAI API key
- ngrok or localtunnel account for local testing
- Heroku account for deployment
-
Clone the repository:
git clone https://github.com/yourusername/whatsapp-survey-bot.git cd whatsapp-survey-bot
-
Install dependencies:
pip install -r requirements.txt
-
Set up environment variables: Create a
.env
file in the project root with the following:OPENAI_API_KEY='Your OpenAI API Key' TWILIO_ACCOUNT_SID='Your Twilio Account SID' TWILIO_AUTH_TOKEN='Your Twilio Auth Token' TWILIO_NUMBER='Your Twilio WhatsApp Number' GOOGLE_APPLICATION_CREDENTIALS='Path to your Firebase admin SDK JSON file'
-
Run the server locally:
uvicorn yourmainfilename:app --reload
To test the application locally, expose your local server to the internet using either ngrok or localtunnel:
-
Using ngrok:
ngrok http 8000
This will provide you with a public URL that you can use in Twilio's WhatsApp webhook settings.
-
Using localtunnel:
npx localtunnel --port 8000
Similar to ngrok, this will provide a public URL to use with Twilio.
Update the webhook URL in your Twilio dashboard to point to the URL provided by ngrok or localtunnel.
-
Create a Heroku app:
heroku create your-app-name
-
Add buildpacks:
heroku buildpacks:set heroku/python
-
Set environment variables on Heroku:
heroku config:set OPENAI_API_KEY='Your OpenAI API Key' heroku config:set TWILIO_ACCOUNT_SID='Your Twilio Account SID' heroku config:set TWILIO_AUTH_TOKEN='Your Twilio Auth Token' heroku config:set TWILIO_NUMBER='Your Twilio WhatsApp Number'
-
Deploy your application:
git push heroku master
-
Update Twilio's webhook URL to point to your Heroku app.
Begin by sending a WhatsApp message to the configured Twilio number. The bot will engage you in a conversation, guiding you through a series of structured questions to gather insights.
- Initial Greeting: Warmly welcomes users and seeks consent for participation.
- Conducting the Survey: Methodically presents questions, maintaining clarity and focus throughout.
- Dynamic Response Handling: Adaptively manages user responses, prompting further discussion where necessary.
- Conclusion: Graciously concludes the interaction after all questions are addressed.
- Contextual Continuity: Keeps track of conversation context effectively, even with brief user responses.
- Adaptive Response Management: Smartly adjusts to varied user inputs to keep discussions on track.
- Exception Handling: Expertly handles unexpected inputs or deviations without disrupting the conversation flow.