{"id":38915231,"url":"https://github.com/rishabkumar7/twilio-cr-byom","last_synced_at":"2026-01-17T15:25:30.644Z","repository":{"id":312855211,"uuid":"1044393716","full_name":"rishabkumar7/twilio-cr-byom","owner":"rishabkumar7","description":"Twilio ConversationRelay demo - BYOM - Bring Your Own Model","archived":false,"fork":false,"pushed_at":"2025-09-24T17:47:29.000Z","size":67,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-14T18:43:33.423Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rishabkumar7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-25T16:03:50.000Z","updated_at":"2025-09-24T17:47:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"83f82da0-e377-4be1-b801-b0ec06728d8c","html_url":"https://github.com/rishabkumar7/twilio-cr-byom","commit_stats":null,"previous_names":["rishabkumar7/twilio-cr-byom"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rishabkumar7/twilio-cr-byom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabkumar7%2Ftwilio-cr-byom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabkumar7%2Ftwilio-cr-byom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabkumar7%2Ftwilio-cr-byom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabkumar7%2Ftwilio-cr-byom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rishabkumar7","download_url":"https://codeload.github.com/rishabkumar7/twilio-cr-byom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabkumar7%2Ftwilio-cr-byom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28511433,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T15:25:30.033Z","updated_at":"2026-01-17T15:25:30.589Z","avatar_url":"https://github.com/rishabkumar7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Voice Assistant with Web Configuration\n\nThis project creates an intelligent voice assistant that uses [Twilio Voice](https://www.twilio.com/docs/voice) and [ConversationRelay](https://www.twilio.com/docs/voice/twiml/connect/conversationrelay) with multiple AI models including [OpenAI API](https://platform.openai.com/docs/api-reference/introduction) and [Google Gemini](https://ai.google.dev/). The assistant can engage in natural two-way conversations over phone calls with configurable personalities and AI models.\n\n## Overview\n\nThis application provides:\n- **Web Configuration Interface**: Select AI models (OpenAI GPT-4o, GPT-4, Gemini) and personality types\n- **Inbound Calls**: Users can call your Twilio number to interact with the AI assistant\n- **Outbound Calls**: Initiate calls to users directly from the web interface\n- **Multiple AI Models**: Support for OpenAI GPT models and Google Gemini\n- **Personality Customization**: Choose from 8 different personality types or create custom prompts\n- **Real-time Configuration**: Changes apply immediately to new calls\n\n## Prerequisites\n\n- [Python 3.10+](https://www.python.org/downloads/)\n- A Twilio Account: Sign up for a [free trial here](https://www.twilio.com/try-twilio)\n- A Twilio Number with Voice Capabilities: [Instructions to purchase a number](https://support.twilio.com/hc/en-us/articles/223180928-How-to-Buy-a-Twilio-Phone-Number)\n- **Required**: OpenAI Account and API Key: Visit [OpenAI's platform](https://platform.openai.com/api-keys)\n- **Optional**: Google AI Studio Account and API Key: Visit [Google AI Studio](https://aistudio.google.com/app/apikey) for Gemini models\n- ngrok for local development: [Download ngrok](https://ngrok.com/)\n\n## Installation\n\n1.  Clone this repository\n    ```bash\n    git clone \u003crepository-url\u003e\n    cd twilio-cr-ai\n    ```\n\n2.  Install the required dependencies:\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n3.  Configure your environment variables:\n    ```bash\n    cp .env.example .env\n    ```\n    \n    Edit the `.env` file with your credentials:\n    ```env\n    # Required - OpenAI API Configuration\n    OPENAI_API_KEY=your_openai_api_key_here\n    \n    # Required - Twilio Configuration\n    TWILIO_ACCOUNT_SID=your_twilio_account_sid\n    TWILIO_AUTH_TOKEN=your_twilio_auth_token\n    TWILIO_PHONE_NUMBER=+1234567890\n    \n    # Optional - Google Gemini API Configuration\n    GEMINI_API_KEY=your_gemini_api_key_here\n    \n    # Required - Ngrok Configuration (without https://)\n    NGROK_URL=your-ngrok-url.ngrok.io\n    ```\n\n## Usage\n\n### Setup and Start the Server\n\n1.  Start ngrok to expose your local server:\n    ```bash\n    ngrok http 8080\n    ```\n\n2.  Update the `NGROK_URL` in your `.env` file with the new URL from ngrok (without https://)\n    ```env\n    NGROK_URL=abc123.ngrok.io\n    ```\n    \n3.  Run the application:\n    ```bash\n    python main.py\n    ```\n\n4.  Configure your Twilio phone number webhook:\n    - Go to [Twilio Console \u003e Phone Numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming)\n    - Select your phone number\n    - Set the webhook URL to: `https://your-ngrok-url.ngrok.io/twiml`\n\n### Using the Web Interface\n\n1.  Open your browser and go to: `http://localhost:8080`\n\n2.  **Configure AI Settings:**\n    - Select your preferred AI model (OpenAI GPT-4o, GPT-4, or Gemini)\n    - Choose a personality type (Helpful, Friendly, Professional, Creative, etc.)\n    - Optionally, add a custom system prompt\n    - Click \"Save Configuration\"\n\n3.  **Make Outbound Calls:**\n    - Enter the recipient's name and phone number (include country code)\n    - Click \"Call Me Now\"\n    - The system will call the specified number with your configured AI assistant\n\n4.  **Receive Inbound Calls:**\n    - Users can call your Twilio number directly\n    - They'll interact with the AI using your current configuration settings\n    \n### Count Calls to Your Twilio Number\n\nUse the helper script to count calls to/from your configured Twilio number in a time range.\n\nRequirements: `.env` must have `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, and `TWILIO_PHONE_NUMBER`.\n\nExamples:\n\n```bash\n# All calls (inbound + outbound) during January (UTC) — default\npython scripts/call_count.py --start 2025-01-01 --end 2025-01-31\n\n# Inbound only or outbound only\npython scripts/call_count.py --start 2025-01-01 --end 2025-01-31 --inbound\npython scripts/call_count.py --start 2025-01-01 --end 2025-01-31 --outbound\n\n# Specific window using ISO-8601 with Z/offset\npython scripts/call_count.py --start 2025-01-01T00:00 --end 2025-01-01T12:00Z\n\n# Include a per-status breakdown\npython scripts/call_count.py --start 2025-01-01 --end 2025-01-31 --status-breakdown\n```\n\nNotes:\n- Dates are interpreted as UTC unless you include a timezone offset or `Z`.\n- Default counts both inbound and outbound.\n- `--inbound` counts only calls where `to` equals your Twilio number.\n- `--outbound` counts only calls where `from` equals your Twilio number.\n\n## How It Works\n\n### Inbound Calls\n1.  User calls your Twilio number\n2.  Twilio requests TwiML from `/twiml` endpoint\n3.  TwiML instructs Twilio to connect to WebSocket at `/ws`\n4.  Voice input is sent to the server via WebSocket\n5.  Server sends input to the configured AI model (OpenAI/Gemini)\n6.  AI response is sent back to Twilio and converted to speech\n7.  Conversation continues until call ends\n\n### Outbound Calls\n1.  User enters name and phone number on web interface\n2.  Server uses Twilio API to initiate call\n3.  When recipient answers, they hear a personalized greeting\n4.  Same WebSocket flow as inbound calls for conversation\n\n### AI Model Selection\n- **OpenAI Models**: GPT-4o Mini (default), GPT-4o, GPT-4\n- **Google Gemini**: Gemini Pro, Gemini Flash\n- Models are switched dynamically based on web configuration\n\n## Project Structure\n\n```\ntwilio-cr-ai/\n├── main.py              # Main FastAPI application with AI model integration\n├── templates/\n│   └── index.html       # Web configuration interface\n├── static/\n│   ├── style.css        # Web interface styling\n│   └── script.js        # Frontend JavaScript for configuration and calls\n├── requirements.txt     # Python dependencies\n├── .env                 # Environment variables (create from .env.example)\n├── .env.example         # Template for environment variables\n└── README.md           # This file\n```\n\n## Available Personality Types\n\n- **Helpful**: A standard helpful assistant\n- **Friendly**: Enthusiastic and supportive companion  \n- **Professional**: Clear, structured, authoritative advisor\n- **Creative**: Imaginative thinker who explores possibilities\n- **Witty**: Conversationalist with humor and clever wordplay\n- **Empathetic**: Understanding listener with emotional support\n- **Technical**: Expert at explaining complex concepts clearly\n- **Casual**: Relaxed, informal, easy-to-talk-to friend\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Twilio configuration incomplete\" error**\n   - Ensure all Twilio environment variables are set in `.env`\n   - Check that your Twilio credentials are correct\n\n2. **AI model not working**\n   - Verify API keys are correctly set\n   - For Gemini models, ensure `GEMINI_API_KEY` is configured\n\n3. **Calls not connecting**\n   - Confirm ngrok is running and URL is updated in `.env`\n   - Check Twilio webhook configuration\n   - Ensure phone numbers include country codes\n\n4. **Web interface not loading**\n   - Confirm server is running on port 8080\n   - Check that `templates/` and `static/` directories exist\n\n### Getting Help\n\n- Check [Twilio Documentation](https://www.twilio.com/docs) for Twilio-specific issues\n- Visit [OpenAI Documentation](https://platform.openai.com/docs) for API-related questions\n- Review [Gemini API Documentation](https://ai.google.dev/docs) for Gemini model issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishabkumar7%2Ftwilio-cr-byom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frishabkumar7%2Ftwilio-cr-byom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishabkumar7%2Ftwilio-cr-byom/lists"}