michangarrito/docs/02-integraciones/INT-009-whisper.md

id	type	title	provider	status	integration_type	created_at	updated_at	simco_version	tags
INT-009	Integration	Transcripción de audio	OpenAI Whisper	Pendiente	Speech-to-Text	2026-01-10	2026-01-10	3.8.0	audio transcripcion whisper openai speech-to-text whatsapp

INT-009: Transcripción de audio

Metadata

Campo	Valor
Codigo	INT-009
Proveedor	OpenAI Whisper
Tipo	Speech-to-Text
Estado	Pendiente
Multi-tenant	Si
Fecha planeada	2026-Q1
Owner	Backend Team

---

1. Descripcion

Integración con OpenAI Whisper API para transcripción automática de mensajes de voz. Permite convertir los audios recibidos por WhatsApp en texto, facilitando el procesamiento automático de pedidos por voz y mejorando la experiencia del cliente que prefiere enviar notas de voz en lugar de escribir.

Casos de uso principales:

• Transcripción de mensajes de voz de WhatsApp de clientes
• Procesamiento de pedidos dictados por voz
• Generación de registros de conversaciones por audio
• Búsqueda de contenido en mensajes de voz históricos
• Accesibilidad para usuarios con dificultades de lectura

---

2. Credenciales Requeridas

Variables de Entorno

Variable	Descripcion	Tipo	Obligatorio
OPENAI_API_KEY	API key de OpenAI	string	SI
WHISPER_MODEL	Modelo a usar (whisper-1)	string	SI
WHISPER_LANGUAGE	Idioma por defecto (es)	string	NO
WHISPER_RESPONSE_FORMAT	Formato de respuesta (json, text, srt, vtt)	string	NO
OPENAI_ORG_ID	ID de organización OpenAI (opcional)	string	NO

Ejemplo de .env

# OpenAI Whisper Transcription
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WHISPER_MODEL=whisper-1
WHISPER_LANGUAGE=es
WHISPER_RESPONSE_FORMAT=json
OPENAI_ORG_ID=org-xxxxxxxxxxxxxxxx

---

3. Arquitectura

┌─────────────────────────────────────────────────────────────────────────┐
│                           MiChangarrito                                 │
│  ┌────────────────┐    ┌──────────────┐    ┌────────────────────────┐  │
│  │  WhatsApp      │───▶│  Message     │───▶│   WhisperService       │  │
│  │  Webhook       │    │  Processor   │    │                        │  │
│  │  (Audio msg)   │    │              │    │  - Download audio      │  │
│  └────────────────┘    └──────────────┘    │  - Convert format      │  │
│                                            │  - Transcribe          │  │
│                                            │  - Parse intent        │  │
│                                            └───────────┬────────────┘  │
└────────────────────────────────────────────────────────┼───────────────┘
                                                         │
                               ┌─────────────────────────┴─────────────────┐
                               │                                           │
                               ▼                                           ▼
                    ┌──────────────────┐                        ┌──────────────────┐
                    │   OpenAI API     │                        │   LLM Service    │
                    │   Whisper        │                        │   (Intent/NER)   │
                    │                  │                        │                  │
                    │  Audio → Texto   │                        │  Texto → Pedido  │
                    └──────────────────┘                        └──────────────────┘

Flujo de Procesamiento de Audio

1. Cliente envía nota de voz por WhatsApp
2. Webhook recibe mensaje con media_id del audio
3. Sistema descarga archivo de audio de WhatsApp
4. Audio se convierte a formato compatible (mp3/wav)
5. WhisperService envía audio a OpenAI Whisper API
6. API retorna transcripción en español
7. Texto se procesa con LLM para extraer intención
8. Si es pedido, se extrae productos y cantidades
9. Se responde al cliente confirmando pedido

---

4. Endpoints

Endpoints Consumidos (OpenAI Whisper API)

Método	Endpoint	Descripción
POST	/v1/audio/transcriptions	Transcribir audio a texto
POST	/v1/audio/translations	Transcribir y traducir a inglés

Parámetros de Request

Parámetro	Tipo	Descripción
file	file	Archivo de audio (mp3, wav, m4a, etc.)
model	string	Modelo: "whisper-1"
language	string	Código ISO-639-1 (ej: "es")
response_format	string	json, text, srt, verbose_json, vtt
temperature	float	0-1, mayor = más creativo
prompt	string	Contexto para mejorar precisión

Endpoints Expuestos (MiChangarrito)

Método	Endpoint	Descripción
POST	/api/v1/audio/transcribe	Transcribir audio subido
POST	/api/v1/audio/transcribe-url	Transcribir desde URL
GET	/api/v1/audio/transcriptions/{id}	Obtener transcripción
GET	/api/v1/audio/transcriptions	Listar transcripciones

---

5. Notas de Implementacion

• Whisper soporta: mp3, mp4, mpeg, mpga, m4a, wav, webm
• Tamaño máximo de archivo: 25MB
• Para audios largos, segmentar en chunks de ~10 minutos
• Usar language: "es" para mejor precisión en español mexicano
• El prompt puede incluir términos del dominio (productos del changarro)
• Costo aproximado: $0.006 USD por minuto de audio
• Implementar cola para procesar audios en background
• Guardar transcripciones para evitar reprocesar
• WhatsApp envía audios en formato OGG/Opus, convertir a mp3
• Usar ffmpeg para conversión de formatos
• Implementar fallback si Whisper falla (mensaje de error al usuario)
• Considerar modelo Whisper local para reducir costos a largo plazo
• Manejar rate limits: 50 RPM para whisper-1
• La transcripción incluye timestamps en formato verbose_json
• Implementar detección de idioma automática para clientes no hispanohablantes