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:

{
  "enabled": true,
  "defaultVoiceProfileId": "profile_id_or_null",
  "storeGeneratedAudio": true,
  "retentionDays": 7
}

Create an AI Employee profile:

{
  "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

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

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

Agent Skills

Agent Cortex

Livia - 360 Assistant

Conversations

VoiceFlux

Access Groups

VoiceFlux

VoiceFlux

Overview

Activation Controls

Dedicated VoiceFlux Page

Voice Profiles

Endpoint Reference

Payloads

Examples

Model and Reliability Policy

Best Practices

Troubleshooting

​VoiceFlux

​Overview

​Activation Controls

​Dedicated VoiceFlux Page

​Voice Profiles

​Endpoint Reference

​Payloads

​Examples

​Model and Reliability Policy

​Best Practices

​Troubleshooting

VoiceFlux

Overview

Activation Controls

Dedicated VoiceFlux Page

Voice Profiles

Endpoint Reference

Payloads

Examples

Model and Reliability Policy

Best Practices

Troubleshooting