Skip to main content

​
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

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:
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:

​
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.