> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de flujo de voz

> Arquitectura interna de VoiceFlux, rutas, formas de consulta de Prisma, política de modelo, entrega de trabajadores, facturación, retención y contratos de seguridad.

# API de flujo de voz

> Referencia interna del desarrollador. La base de evidencia es el paquete de auditoría completo en `docs/voiceflux/`, especialmente los documentos 01, 04, 07, 09, 11 y 12 más `voiceflux-audit-manifest.json`.

## Mapa de ruta

| Método         | Ruta                           | Autorización                   | Consulta de inquilino indexada                                       |
| -------------- | ------------------------------ | ------------------------------ | -------------------------------------------------------------------- |
| `GET/PATCH`    | `/api/voiceflux/settings`      | leer unión / `billing.manage`  | único `organizationId`                                               |
| `GET/POST`     | `/api/voiceflux/profiles`      | `agents.read` / `agents.write` | `organizationId, enabled, createdAt`                                 |
| `PATCH/DELETE` | `/api/voiceflux/profiles/[id]` | `agents.write`                 | directo `id` más `organizationId` aislamiento                        |
| `GET`          | `/api/voiceflux/usage`         | `billing.read` o `agents.read` | `organizationId, periodEnd`                                          |
| `GET`          | `/api/voiceflux/jobs`          | `logs.read`                    | directo `conversationId, createdAt` más `organizationId` aislamiento |

Todos los ID de perfil y de agente proporcionados por los clientes se revalidan con la organización activa. Los diagnósticos de trabajos seleccionan solo el estado, los metadatos del proveedor/modelo, el recuento de intentos, la duración, el código de error seguro y las marcas de tiempo. Nunca devuelven el texto del mensaje, `failureDetail`, `audioStorageKey` o `audioUrl`.

`VoiceFluxSettingsUpdateSchema` excluye intencionalmente `includedAudioSeconds`; los inquilinos no pueden concederse a sí mismos el subsidio de proveedor.

## Persistencia

Modelos principales:

* `OrganizationVoiceFluxSettings`: activación de derechos, estado de suscripción de Stripe, perfil predeterminado, retención, asignación incluida.
* `VoiceFluxProfile`: estilo estructurado con ámbito de organización/agente.
* `VoiceFluxSynthesisJob`: ciclo de vida idempotente y diagnóstico seguro.
* `VoiceFluxUsagePeriod`: UTC mensual incluidos, segundos de audio comprados y usados.

Los campos de activación son `Agent.voiceRepliesEnabled` y ​​`Conversation.voiceFluxEnabled`. La cola requiere ambos campos más `Conversation.isAiEnabled`.

La resolución de perfiles realiza consultas indexadas independientes y aplica `agent profile > organization default > built-in defaults`. No reemplace los filtros directos `organizationId`, `agentId`, `conversationId` o `messageId` con filtros de relación.

## Flujo de tiempo de ejecución

1. `handle-chat-message/handler.ts` persists the normal text answer.
2. `enqueueVoiceFluxForMessage(messageId)` validates emergency/provider state, three-layer activation, channel support, commercial entitlement, and available allowance.
3. A deterministic SHA-256 idempotency key includes message, selected profile/style, and fixed model policy.
4. BullMQ queue `voiceflux-synthesize` runs `processVoiceFluxJob` in `apps/workers-services`.
5. The worker synthesizes OGG/Opus, measures actual duration, reserves usage atomically, uploads privately, and delivers through the existing channel adapter.
6. Any safe failure delivers the already-persisted original text. An uncertain `DELIVERING` retry favors text over duplicate audio.

Los canales de entrega admitidos son Baileys, WhatsApp Cloud, Telegram `sendVoice`, archivo adjunto de audio de Messenger y archivo adjunto de audio de Instagram.

## Política de modelo fijo

Las constantes de backend están codificadas y no son configurables por el inquilino o el entorno:

```text theme={null}
attempt 1: gemini-3.1-flash-tts-preview
attempt 2: gemini-3.1-flash-tts-preview
recovery:  gemini-2.5-flash-tts (only after both 3.1 failures)
```

`gemini-3.1-flash-tts-preview` se trata como estable y operativo y es la única base de precios/capacidad. No se permite ninguna rama más allá de los dos ID enumerados anteriormente. Los cambios requieren actualizar el paquete de auditoría `docs/voiceflux` completo y las pruebas de política del proveedor.

## Medición y retención

La duración se mide a partir de la salida OGG/Opus generada y se redondea a un segundo completo. `meterVoiceFluxAudioSeconds` utiliza una transacción y un `updateMany` condicional para reservar la asignación de forma atómica. El consumo del proveedor aún se mide si la síntesis se completó después de que otra solicitud simultánea agotó la asignación de entrega.

Los objetos cargados reciben `expiresAt`. El trabajador de VoiceFlux escanea la columna de vencimiento indexada cada hora, elimina hasta 100 objetos S3 vencidos por lote y borra las referencias de almacenamiento. La configuración de almacenamiento faltante deshabilita la limpieza sin eliminar los registros de auditoría de trabajos.

## Facturación y Stripe

VoiceFlux es un módulo de crecimiento `level_2+`. El proceso de pago copia `organizationId` y ​​`growthModuleKey` en los metadatos de la suscripción. Los eventos de webhook de suscripción y finalización de pago sincronizan la lista de módulos de suscripción base y `OrganizationVoiceFluxSettings.stripeSubscriptionId/status`. Las suscripciones complementarias inactivas o eliminadas desactivan VoiceFlux de la organización.

El webhook sigue siendo la fuente comercial de verdad. La interfaz de usuario no puede activar VoiceFlux cuando falta la elegibilidad del plan o el estado del complemento.

## Contrato de interfaz

Objetivos de dramaturgo requeridos:

| Superficie                                                    | Selector                          |
| ------------------------------------------------------------- | --------------------------------- |
| Registros de conversación debajo de AI habilitar/deshabilitar | `logs-voiceflux`                  |
| Configuración existente de empleados de IA                    | `agent-settings-voiceflux`        |
| Nuevo modo de empleado de IA                                  | `new-agent-voiceflux`             |
| Editor de perfil de voz del agente                            | `agent-voiceflux-profile`         |
| Configuración de la organización                              | `voiceflux-organization-settings` |
| Último diagnóstico de conversación segura                     | `logs-voiceflux-diagnostic`       |

## Problemas

* Nunca suprima la respuesta de texto normal a menos que el trabajo de VoiceFlux se haya puesto en cola con éxito.
* Nunca registre texto de respuesta sin procesar, credenciales, cargas útiles del proveedor, URL de audio o detalles de errores internos.
* No reintente los trabajos de síntesis de BullMQ independientemente del adaptador del proveedor; el adaptador posee el techo de intento de modelo exacto.
* No exponga los ID de los modelos como configuraciones del producto.
* No agregue escrituras permitidas al esquema de configuración pública.
* Mantenga el manejo de cancelaciones de Stripe sincronizado con la activación de la organización.

## Verificación

Ejecute las suites VoiceFlux Jest, comprobaciones de tipo de panel/trabajador/lib, comprobaciones prácticas de Playwright para todos los selectores necesarios, validación de Prisma, scripts de traducción/navegación de documentos y, finalmente, la actualización forzada de Graphify requerida.