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

# Fluxo de Voz

> Configure respostas de voz sintetizadas contextuais para funcionários de IA, conversas, faturamento, uso e perfis de voz.

\#VoiceFlux

## Visão geral

VoiceFlux converte uma resposta de texto persistente de um funcionário de IA em áudio contextual sintetizado para WhatsApp, Baileys, Telegram, Messenger e Instagram. O texto original continua sendo a resposta de recuperação sempre que a síntese, a concessão, o armazenamento ou a entrega não puderem ser concluídos com segurança.

VoiceFlux requer um plano Pro ou superior, um complemento VoiceFlux ativo, ativação de organização, ativação de funcionário de IA e ativação de conversa. O uso é medido em segundos de áudio gerados.

A implementação segue a arquitetura validada e as evidências em `docs/voiceflux/01-current-audio-pipeline-audit.md` até `docs/voiceflux/12-orchestrator-implementation-prompt.md`.

## Controles de ativação

Todos os três controles devem estar habilitados:

| Localização                                                           | Controle                         | Finalidade                                                       |
| --------------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------- |
| **Configurações → Faturamento**                                       | Mudança VoiceFlux da organização | Ativa o complemento adquirido para a organização                 |
| **Funcionários de IA → Novo funcionário de IA**                       | Caixa de seleção VoiceFlux       | Define `voiceRepliesEnabled` durante a criação                   |
| **Funcionário de IA → Configurações**                                 | Caixa de seleção VoiceFlux       | Atualizações `voiceRepliesEnabled` para um funcionário existente |
| **Registros de conversas**, diretamente abaixo de ativar/desativar IA | Caixa de seleção VoiceFlux       | Define `voiceFluxEnabled` para essa conversa                     |

O controle de conversação não está disponível quando a IA está desativada, o funcionário da IA ​​atribuído tem respostas de voz desativadas, o canal não é compatível ou o direito comercial está inativo.

## Perfis de voz

Abra as configurações de um funcionário AI para configurar seu perfil VoiceFlux:

* voz e localidade
* tom e intensidade emocional
* ritmo e formalidade

Um perfil de Funcionário AI tem precedência sobre o perfil padrão da organização. Sem nenhum dos perfis, o VoiceFlux usa seus padrões de estilo integrados seguros.

Os administradores de faturamento da organização podem escolher o perfil padrão, se o áudio gerado será retido e um período de retenção de 1 a 30 dias. O áudio expirado é removido automaticamente.

## Referência de terminal

| Método   | Ponto final                               | Permissão                                    | Descrição                                                   |
| -------- | ----------------------------------------- | -------------------------------------------- | ----------------------------------------------------------- |
| `GET`    | `/api/voiceflux/settings`                 | `agents.read`, `logs.read` ou `billing.read` | Leia o estado comercial e organizacional                    |
| `PATCH`  | `/api/voiceflux/settings`                 | `billing.manage`                             | Atualizar ativação da organização, perfil padrão e retenção |
| `GET`    | `/api/voiceflux/profiles`                 | `agents.read`                                | Listar perfis de voz da organização                         |
| `POST`   | `/api/voiceflux/profiles`                 | `agents.write`                               | Crie uma organização ou perfil de funcionário de IA         |
| `PATCH`  | `/api/voiceflux/profiles/{id}`            | `agents.write`                               | Atualizar um perfil de propriedade do locatário             |
| `DELETE` | `/api/voiceflux/profiles/{id}`            | `agents.write`                               | Excluir um perfil de propriedade do locatário               |
| `GET`    | `/api/voiceflux/usage`                    | `billing.read` ou `agents.read`              | Leia o uso atual de áudio no período UTC                    |
| `GET`    | `/api/voiceflux/jobs?conversationId={id}` | `logs.read`                                  | Leia diagnósticos de síntese segura para uma conversa       |

## Cargas úteis

Atualize as configurações da organização:

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

Crie um perfil de funcionário AI:

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

A franquia incluída é controlada pelo ciclo de vida da assinatura e não pode ser aumentada por meio da API de configurações.

## Exemplos

```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 e Política de Confiabilidade

`gemini-3.1-flash-tts-preview` é o único modelo VoiceFlux operacional e comercial estável. Um trabalho pode chamá-lo no máximo duas vezes. Somente após a falha de ambas as chamadas o back-end poderá fazer uma chamada de recuperação final para `gemini-2.5-flash-tts`. Não há seletor de modelo na interface do usuário, nas configurações do locatário ou nas variáveis ​​de ambiente, e o preço do modelo de recuperação não é usado como linha de base comercial.

## Melhores práticas

* Habilite o VoiceFlux primeiro no nível da organização, depois para o funcionário de IA e depois para cada conversa pretendida.
* Mantenha os perfis concisos e use opções de estilo estruturado em vez de incorporar instruções de entrega em texto de IA.
* Revise os segundos de áudio restantes no faturamento e diagnósticos de trabalhos recentes nos registros de conversas.
* Utilize o menor período de retenção compatível com os requisitos operacionais.

## Solução de problemas

| Sintoma                                      | Causa                                                                      | Resolução                                                                     |
| -------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| A caixa de seleção VoiceFlux está desativada | Falta de IA, funcionário de IA, canal, plano ou pré-requisito complementar | Leia o motivo ao lado do controle e habilite o pré-requisito                  |
| Texto foi enviado em vez de áudio            | Síntese, permissão, armazenamento ou recuperação de entrega ativada        | Inspecione o diagnóstico mais recente do VoiceFlux nos registros de conversa  |
| O perfil não pode ser editado                | O direito da organização está inativo                                      | Ative o complemento e a opção de organização em Faturamento                   |
| Os segundos restantes são zero               | Esgotado o subsídio mensal incluído e adquirido                            | Aguarde o próximo período UTC ou adquira uma recarga futura quando disponível |