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

# VoiceFlux

> Configure contextual synthesized voice replies for AI Employees, conversations, billing, usage, and voice profiles.

# VoiceFlux

## Overview

VoiceFlux converts a persisted AI Employee text reply into contextual synthesized audio for WhatsApp, Baileys, Telegram, Messenger, and Instagram. The original text remains the recovery response whenever synthesis, allowance, storage, or delivery cannot complete safely.

VoiceFlux requires a Pro plan or higher, an active VoiceFlux add-on, organization activation, AI Employee activation, and conversation activation. Usage is measured in generated audio seconds.

The implementation follows the validated architecture and evidence in `docs/voiceflux/01-current-audio-pipeline-audit.md` through `docs/voiceflux/12-orchestrator-implementation-prompt.md`.

## Activation Controls

All three controls must be enabled:

| Location                                                | Control                       | Purpose                                                |
| ------------------------------------------------------- | ----------------------------- | ------------------------------------------------------ |
| **Settings → Billing**                                  | Organization VoiceFlux switch | Activates the purchased add-on for the organization    |
| **AI Employees → New AI Employee**                      | VoiceFlux checkbox            | Sets `voiceRepliesEnabled` during creation             |
| **AI Employee → Settings**                              | VoiceFlux checkbox            | Updates `voiceRepliesEnabled` for an existing employee |
| **Conversation Logs**, directly below AI enable/disable | VoiceFlux checkbox            | Sets `voiceFluxEnabled` for that conversation          |

The conversation control is unavailable when AI is disabled, the assigned AI Employee has voice replies disabled, the channel is unsupported, or the commercial entitlement is inactive.

## Dedicated VoiceFlux Page

Open **VoiceFlux** from the main navigation. Its button is directly below **Livia** and before **ZappFlux** in both expanded and collapsed navigation.

The dedicated page brings the operational and commercial controls together:

* current plan/add-on status and a direct Billing action
* included, consumed, and remaining audio allowance
* reusable voice characters for all or selected AI Employees
* voice, locale, tone, intensity, pace, and formality
* organization activation, default character, safe text fallback, audio retention, and retention period

Users with `agents.read` can view the page. Profile changes require `agents.write`, while organization policy changes require `billing.manage`.

## Voice Profiles

Use the dedicated VoiceFlux page to manage reusable organization and AI Employee characters, or open an AI Employee's settings to configure its assigned VoiceFlux profile:

* voice and locale
* tone and emotional intensity
* pace and formality

An AI Employee profile takes precedence over the organization's default profile. Without either profile, VoiceFlux uses its safe built-in style defaults.

Organization billing administrators can choose the default profile, whether generated audio is retained, and a retention period from 1 to 30 days. Expired audio is removed automatically.

## Endpoint Reference

| Method   | Endpoint                                  | Permission                                    | Description                                                    |
| -------- | ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------- |
| `GET`    | `/api/voiceflux/settings`                 | `agents.read`, `logs.read`, or `billing.read` | Read commercial and organization state                         |
| `PATCH`  | `/api/voiceflux/settings`                 | `billing.manage`                              | Update organization activation, default profile, and retention |
| `GET`    | `/api/voiceflux/profiles`                 | `agents.read`                                 | List organization voice profiles                               |
| `POST`   | `/api/voiceflux/profiles`                 | `agents.write`                                | Create an organization or AI Employee profile                  |
| `PATCH`  | `/api/voiceflux/profiles/{id}`            | `agents.write`                                | Update a tenant-owned profile                                  |
| `DELETE` | `/api/voiceflux/profiles/{id}`            | `agents.write`                                | Delete a tenant-owned profile                                  |
| `GET`    | `/api/voiceflux/usage`                    | `billing.read` or `agents.read`               | Read current UTC-period audio usage                            |
| `GET`    | `/api/voiceflux/jobs?conversationId={id}` | `logs.read`                                   | Read safe synthesis diagnostics for a conversation             |

## Payloads

Update organization settings:

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

Create an AI Employee profile:

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

The included allowance is controlled by the subscription lifecycle and cannot be increased through the settings API.

## Examples

```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,
  }),
});
```

## Model and Reliability Policy

`gemini-3.1-flash-tts-preview` is the stable, sole operational and commercial VoiceFlux model. A job can call it at most twice. Only after both calls fail may the backend make one final recovery call to `gemini-2.5-flash-tts`. There is no model selector in the UI, tenant settings, or environment variables, and recovery-model pricing is not used as the commercial baseline.

VoiceFlux reaches Google directly through the official Gemini API. The server uses its existing `GOOGLE_AI_API_KEY`; it does not require Google Cloud project/location settings and does not route synthesis through OpenRouter.

## Best Practices

* Enable VoiceFlux first at organization level, then for the AI Employee, then for each intended conversation.
* Keep profiles concise and use structured style options rather than embedding delivery instructions in AI text.
* Review remaining audio seconds on Billing and recent job diagnostics in Conversation Logs.
* Use the shortest retention period compatible with operational requirements.

## Troubleshooting

| Symptom                        | Cause                                                             | Resolution                                                              |
| ------------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
| VoiceFlux checkbox is disabled | AI, AI Employee, channel, plan, or add-on prerequisite is missing | Read the reason beside the control and enable the prerequisite          |
| Text was sent instead of audio | Synthesis, allowance, storage, or delivery recovery activated     | Inspect the latest VoiceFlux diagnostic in Conversation Logs            |
| Profile cannot be edited       | Organization entitlement is inactive                              | Activate the add-on and organization switch under Billing               |
| Remaining seconds are zero     | Monthly included and purchased allowance is exhausted             | Wait for the next UTC period or purchase a future top-up when available |