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

# Flujo de voz

> Configure respuestas de voz sintetizadas contextuales para empleados de IA, conversaciones, facturación, uso y perfiles de voz.

# flujo de voz

## Descripción general

VoiceFlux convierte una respuesta de texto persistente de un empleado de IA en audio sintetizado contextual para WhatsApp, Baileys, Telegram, Messenger e Instagram. El texto original sigue siendo la respuesta de recuperación siempre que la síntesis, la asignación, el almacenamiento o la entrega no se puedan completar de forma segura.

VoiceFlux requiere un plan Pro o superior, un complemento VoiceFlux activo, activación de organización, activación de empleado de IA y activación de conversación. El uso se mide en segundos de audio generado.

La implementación sigue la arquitectura validada y la evidencia desde `docs/voiceflux/01-current-audio-pipeline-audit.md` hasta `docs/voiceflux/12-orchestrator-implementation-prompt.md`.

## Controles de activación

Los tres controles deben estar habilitados:

| Ubicación                                                                       | Controlar                             | Propósito                                                        |
| ------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------- |
| **Configuración → Facturación**                                                 | Organización del conmutador VoiceFlux | Activa el complemento adquirido para la organización             |
| **Empleados de IA → Nuevo empleado de IA**                                      | Casilla de verificación VoiceFlux     | Establece `voiceRepliesEnabled` durante la creación              |
| **Empleado de IA → Configuración**                                              | Casilla de verificación VoiceFlux     | Actualizaciones `voiceRepliesEnabled` para un empleado existente |
| **Registros de conversación**, directamente debajo de habilitar/deshabilitar IA | Casilla de verificación VoiceFlux     | Establece `voiceFluxEnabled` para esa conversación               |

El control de conversación no está disponible cuando la IA está deshabilitada, el empleado de IA asignado tiene las respuestas de voz deshabilitadas, el canal no es compatible o el derecho comercial está inactivo.

## Perfiles de voz

Abra la configuración de un empleado de AI para configurar su perfil VoiceFlux:

* voz y localidad
* tono e intensidad emocional
* ritmo y formalidad

Un perfil de empleado de IA tiene prioridad sobre el perfil predeterminado de la organización. Sin ninguno de los perfiles, VoiceFlux utiliza sus valores predeterminados de estilo integrados y seguros.

Los administradores de facturación de la organización pueden elegir el perfil predeterminado, si se conserva el audio generado y un período de retención de 1 a 30 días. El audio caducado se elimina automáticamente.

## Referencia de punto final

| Método   | Punto final                               | Permiso                                     | Descripción                                                                          |
| -------- | ----------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------ |
| `GET`    | `/api/voiceflux/settings`                 | `agents.read`, `logs.read` o `billing.read` | Leer estado comercial y de organización                                              |
| `PATCH`  | `/api/voiceflux/settings`                 | `billing.manage`                            | Actualizar la activación, el perfil predeterminado y la retención de la organización |
| `GET`    | `/api/voiceflux/profiles`                 | `agents.read`                               | Listar perfiles de voz de organizaciones                                             |
| `POST`   | `/api/voiceflux/profiles`                 | `agents.write`                              | Crear una organización o un perfil de empleado de IA                                 |
| `PATCH`  | `/api/voiceflux/profiles/{id}`            | `agents.write`                              | Actualizar un perfil de propiedad del inquilino                                      |
| `DELETE` | `/api/voiceflux/profiles/{id}`            | `agents.write`                              | Eliminar un perfil propiedad del inquilino                                           |
| `GET`    | `/api/voiceflux/usage`                    | `billing.read` o `agents.read`              | Lea el uso de audio actual del período UTC                                           |
| `GET`    | `/api/voiceflux/jobs?conversationId={id}` | `logs.read`                                 | Lea diagnósticos de síntesis seguros para una conversación                           |

## Cargas útiles

Actualizar la configuración de la organización:

```json theme={null}
{
  "enabled": true,
  "defaultVoiceProfileId": "profile_id_or_null",
  "storeGeneratedAudio": true,
  "retentionDays": 7
}
```

Cree un perfil de empleado de IA:

```json theme={null}
{
  "agentId": "agent_id",
  "name": "Support voice",
  "locale": "pt-BR",
  "voiceName": "Kore",
  "tone": "EMPATHETIC",
  "intensity": "MEDIUM",
  "pace": "NORMAL",
  "formality": "NEUTRAL",
  "enabled": true
}
```

La asignación incluida está controlada por el ciclo de vida de la suscripción y no se puede aumentar a través de la API de configuración.

## Ejemplos

```bash theme={null}
curl -X PATCH "$DASHBOARD_URL/api/voiceflux/settings" \
  -H "content-type: application/json" \
  -H "cookie: $AUTH_COOKIE" \
  --data '{"enabled":true,"storeGeneratedAudio":true,"retentionDays":7}'
```

```ts theme={null}
const response = await fetch('/api/voiceflux/profiles', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    agentId,
    name: 'Support voice',
    locale: 'pt-BR',
    voiceName: 'Kore',
    tone: 'EMPATHETIC',
    intensity: 'MEDIUM',
    pace: 'NORMAL',
    formality: 'NEUTRAL',
    enabled: true,
  }),
});
```

## Modelo y Política de Confiabilidad

`gemini-3.1-flash-tts-preview` es el único modelo estable, operativo y comercial de VoiceFlux. Un trabajo puede llamarlo como máximo dos veces. Solo después de que ambas llamadas fallen, el backend podrá realizar una llamada de recuperación final a `gemini-2.5-flash-tts`. No hay ningún selector de modelo en la interfaz de usuario, la configuración del inquilino ni las variables de entorno, y el precio del modelo de recuperación no se utiliza como base comercial.

## Mejores prácticas

* Habilite VoiceFlux primero a nivel de organización, luego para el empleado de IA y luego para cada conversación prevista.
* Mantenga los perfiles concisos y utilice opciones de estilo estructuradas en lugar de incorporar instrucciones de entrega en texto de IA.
* Revise los segundos de audio restantes en Facturación y diagnósticos de trabajos recientes en Registros de conversación.
* Utilizar el período de retención más corto compatible con los requisitos operativos.

## Solución de problemas

| Síntoma                                                 | Causa                                                                      | Resolución                                                                       |
| ------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| La casilla de verificación VoiceFlux está deshabilitada | Falta el requisito previo de IA, empleado de IA, canal, plan o complemento | Lea el motivo al lado del control y habilite el requisito previo                 |
| Se envió texto en lugar de audio                        | Recuperación de síntesis, asignación, almacenamiento o entrega activada    | Inspeccione el último diagnóstico de VoiceFlux en Registros de conversaciones    |
| El perfil no se puede editar                            | El derecho de organización está inactivo                                   | Active el complemento y el interruptor de organización en Facturación            |
| Los segundos restantes son cero                         | Asignación mensual incluida y comprada agotada                             | Espere al próximo período UTC o compre una recarga futura cuando esté disponible |