Twilio VoiceFlow API Bridge

Pequeño servicio Flask que conecta llamadas de voz de Twilio Voice con flujos conversacionales creados en VoiceFlow. Permite construir IVRs inteligentes, asistentes de soporte y experiencias de autoservicio en español con reconocimiento de voz y DTMF.

Características

• Maneja llamadas entrantes y enruta la conversación a VoiceFlow (state/interact).
• Soporta entrada mixta (DTMF + speech) y voces en español (voice=Mia).
• Gestiona cola de mensajes para texto, audio, call forwarding y fin de llamada.
• Mantiene estado entre turnos utilizando user_id = número telefónico.
• Preparado para desplegarse en plataformas serverless (heroku, fly.io, render, etc.).

Arquitectura

app.py                  # Flask + Twilio webhook
utils/voiceflow_helpers.py
requirements.txt

Variables de entorno

Cree un archivo .env (ver .env.example sugerido):

Variable	Descripción
VF_PROJECT_VERSION_ID	ID del proyecto/versión en VoiceFlow.
VF_API_KEY	API key generada en VoiceFlow (runtime).
TWILIO_AUTH_TOKEN	(Opcional) para validación de firmas.

Instalación

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
flask --app app run --host 0.0.0.0 --port 5000

Configuración Twilio

1. Cree un número de teléfono en Twilio.
2. Configure el Webhook de voz en la URL pública del endpoint /.
3. (Opcional) Configure el webhook de estado de llamada hacia /call-status.

Flujo

1. Twilio envía el POST a / durante la llamada.
2. El servicio consulta VoiceFlow y transforma la respuesta en TwiML (VoiceResponse).
3. Se reproduce audio, se obtienen opciones y se esperan nuevas entradas.
4. El webhook /call-status registra duración y resultado en la base que defina.

Roadmap

• Validación de firmas Twilio (X-Twilio-Signature).
• Almacenamiento persistente de transcripciones.
• Deploy automático con Dockerfile ligero.

Licencia

Proyecto bajo licencia MIT.