{"id":28881984,"url":"https://github.com/ronihdzz/voice-ai-asistant-python","last_synced_at":"2026-05-08T00:41:43.646Z","repository":{"id":298443147,"uuid":"871783287","full_name":"ronihdzz/voice-ai-asistant-python","owner":"ronihdzz","description":"An AI voice assistant for real-time phone conversations, built with Python, Twilio, and OpenAI's Realtime API.","archived":false,"fork":false,"pushed_at":"2025-06-11T05:04:12.000Z","size":60,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-11T06:21:17.057Z","etag":null,"topics":["conversational-ai","docker","fastapi","gpt-4o","openai-api","python","real-time","twilio","voice-assistant"],"latest_commit_sha":null,"homepage":"https://ronihdz.com/","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/ronihdzz.png","metadata":{"files":{"readme":"README.es.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}},"created_at":"2024-10-12T23:25:56.000Z","updated_at":"2025-06-11T05:09:43.000Z","dependencies_parsed_at":"2025-06-11T06:21:41.433Z","dependency_job_id":"1d2d6b35-c758-4db9-84f0-322df78c2cda","html_url":"https://github.com/ronihdzz/voice-ai-asistant-python","commit_stats":null,"previous_names":["ronihdzz/voice-asistant-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ronihdzz/voice-ai-asistant-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Fvoice-ai-asistant-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Fvoice-ai-asistant-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Fvoice-ai-asistant-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Fvoice-ai-asistant-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ronihdzz","download_url":"https://codeload.github.com/ronihdzz/voice-ai-asistant-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronihdzz%2Fvoice-ai-asistant-python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261014135,"owners_count":23097182,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["conversational-ai","docker","fastapi","gpt-4o","openai-api","python","real-time","twilio","voice-assistant"],"created_at":"2025-06-20T20:41:44.931Z","updated_at":"2026-05-08T00:41:43.635Z","avatar_url":"https://github.com/ronihdzz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎙️ Voice AI Assistant con OpenAI Realtime API y Twilio\n\n## Language / Idioma\n- [English](README.md)\n- **Español** (actual)\n\n---\n\nUn asistente de voz inteligente que combina la potencia de **OpenAI Realtime API** con **Twilio Voice** para crear conversaciones de voz en tiempo real. Este proyecto permite realizar llamadas telefónicas y tener conversaciones naturales con un asistente de IA.\n\n\u003e **Nota Importante**: Este proyecto está basado completamente en la documentación oficial de Twilio. He tomado el artículo base y creado un template más organizado y estructurado, pero el concepto y la implementación principal siguen fielmente el tutorial original de Twilio.\n\n## 📖 Referencia Original\n\n- **Artículo base**: [Voice AI Assistant with OpenAI Realtime API and Python](https://www.twilio.com/en-us/blog/voice-ai-assistant-openai-realtime-api-python)\n\nEste proyecto es una reorganización  del código presentado en el artículo oficial de Twilio, manteniendo la misma funcionalidad pero con una estructura más modular y profesional.\n\n## 🚀 ¿Qué hace este proyecto?\n\n- **Recibir llamadas telefónicas** a través de Twilio Voice\n- **Procesar audio en tiempo real** usando WebSockets\n- **Generar respuestas inteligentes** con OpenAI GPT-4o Realtime API  \n- **Responder con voz sintetizada** de vuelta al llamador\n- **Mantener conversaciones naturales** con detección automática de voz\n\n### Características principales:\n\n- ✅ **Conversaciones de voz bidireccionales** en tiempo real\n- ✅ **Detección automática de voz** (Voice Activity Detection)\n- ✅ **Múltiples voces disponibles** (configurables)\n- ✅ **Sistema de logging avanzado** con Loguru\n- ✅ **Configuración por ambientes** (local, development, production)\n- ✅ **Arquitectura modular** con FastAPI\n- ✅ **Containerización** con Docker\n\n## 🏗️ Arquitectura del Sistema\n\n### Componentes principales:\n\n1. **FastAPI Server** - Servidor web que maneja webhooks y WebSockets\n2. **Twilio Voice** - Plataforma de telefonía que recibe las llamadas\n3. **OpenAI Realtime API** - Motor de IA para procesamiento de voz\n4. **WebSocket Bridge** - Puente bidireccional para streaming de audio\n\n## 🔄 Flujo de Interacción y Webhooks\n\n### Fases del Proceso:\n\n#### 🟢 Fase 1: Establecimiento de Llamada \n1. El usuario llama al número de Twilio configurado\n2. Twilio envía un webhook HTTP POST/GET a `/incoming-call`\n3. El servidor responde con TwiML que incluye:\n   - Mensaje de bienvenida (`\u003cSay\u003e`)\n   - Instrucción de conexión WebSocket (`\u003cConnect\u003e\u003cStream\u003e`)\n\n#### 🟡 Fase 2: Establecimiento de Conexiones WebSocket\n1. Twilio conecta al WebSocket `/media-stream` del servidor\n2. El servidor establece conexión con OpenAI Realtime API\n3. Se envía configuración inicial (`session.update`) a OpenAI\n4. OpenAI confirma la configuración (`session.updated`)\n\n#### 🔵 Fase 3: Streaming de Audio Bidireccional\n1. **Twilio → FastAPI**: Audio del usuario como eventos `media` (G.711 μ-law)\n2. **FastAPI → OpenAI**: Audio convertido a base64 (`input_audio_buffer.append`)\n3. **OpenAI → FastAPI**: Respuesta de IA como `response.audio.delta`\n4. **FastAPI → Twilio**: Audio de respuesta procesado\n5. **Twilio → Usuario**: Reproducción de la respuesta de IA\n\n#### 🔴 Fase 4: Finalización \n1. El usuario cuelga la llamada\n2. Twilio desconecta el WebSocket\n3. El servidor cierra la conexión con OpenAI\n\n## ⚙️ Configuración Técnica Detallada\n\n### 🤖 Configuración OpenAI\n```python\nsession_update = {\n    \"type\": \"session.update\",\n    \"session\": {\n        \"turn_detection\": {\"type\": \"server_vad\"},     # Detección automática de voz\n        \"input_audio_format\": \"g711_ulaw\",           # Formato de entrada\n        \"output_audio_format\": \"g711_ulaw\",          # Formato de salida  \n        \"voice\": \"alloy\",                            # Voz configurada\n        \"instructions\": SYSTEM_MESSAGE,              # Prompt del asistente\n        \"modalities\": [\"text\", \"audio\"],             # Modalidades soportadas\n        \"temperature\": 0.8                           # Creatividad de respuestas\n    }\n}\n```\n\n### 🎯 Prompt del Sistema\n```python\nSYSTEM_MESSAGE = (\n    \"You are a helpful and bubbly AI assistant who loves to chat about \"\n    \"anything the user is interested in and is prepared to offer them facts. \" \n    \"You have a penchant for dad jokes, owl jokes, and rickrolling – subtly. \"\n    \"Always stay positive, but work in a joke when appropriate.\"\n)\n```\n\n## 📁 Estructura del Proyecto\n\n```\nvoice-assistant-python/\n├── src/\n│   ├── main.py                 # Servidor principal FastAPI\n│   ├── prompts.py             # Prompts del sistema\n│   └── core/\n│       ├── settings/\n│       │   ├── __init__.py    # Exportaciones de settings\n│       │   └── base.py        # Configuraciones base\n│       └── utils/\n│           └── environment.py  # Manejo de ambientes\n├── envs/                      # Variables de entorno por ambiente\n├── pyproject.toml            # Configuración Poetry\n├── requirements.txt          # Dependencias pip\n├── docker-compose.yml        # Configuración Docker\n├── Dockerfile.deploy         # Dockerfile de producción\n└── README.md                # Este archivo\n```\n\n## 🔧 Tecnologías Utilizadas\n\n- **[FastAPI](https://fastapi.tiangolo.com/)** - Framework web moderno y rápido\n- **[WebSockets](https://websockets.readthedocs.io/)** - Comunicación bidireccional en tiempo real\n- **[Twilio Voice API](https://www.twilio.com/docs/voice)** - Plataforma de telefonía\n- **[OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime)** - IA conversacional en tiempo real\n- **[Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)** - Manejo de configuraciones\n- **[Loguru](https://loguru.readthedocs.io/)** - Sistema de logging avanzado\n- **[Poetry](https://python-poetry.org/)** - Gestión de dependencias\n\n## 🤝 Créditos y Reconocimientos\n\nEste proyecto está **completamente basado** en el excelente tutorial de Twilio:\n\n**\"[Build a Voice AI Assistant with OpenAI's Realtime API and Python](https://www.twilio.com/en-us/blog/voice-ai-assistant-openai-realtime-api-python)\"**\n\n### ¿Qué aporta este repositorio?\n\n- ✨ **Estructura modular y profesional** del código\n- 🏗️ **Configuración por ambientes** (local, dev, prod)\n- 🐳 **Containerización completa** con Docker\n- 📝 **Documentación detallada** y diagramas\n- 🔧 **Manejo de configuraciones** con Pydantic\n- 📊 **Sistema de logging mejorado**\n- 🎯 **Separación de responsabilidades**\n\n## 📞 Funcionamiento \n\n1. **Usuario llama** al número de Twilio configurado\n2. **Escucha el mensaje** de bienvenida\n3. **Empieza a hablar** cuando se le indica\n4. **Mantiene conversación** natural con el asistente\n5. **Cuelga** cuando termina la conversación\n\nEl asistente puede hablar sobre cualquier tema, hacer chistes y mantener conversaciones naturales gracias a GPT-4o. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronihdzz%2Fvoice-ai-asistant-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronihdzz%2Fvoice-ai-asistant-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronihdzz%2Fvoice-ai-asistant-python/lists"}