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

# API VoiceFlux

> Arquitetura interna do VoiceFlux, rotas, formas de consulta Prisma, política de modelo, entrega de trabalhadores, faturamento, retenção e contratos de segurança.

\#API VoiceFlux

> Referência interna do desenvolvedor. A linha de base da evidência é o pacote completo de auditoria em `docs/voiceflux/`, especialmente os documentos 01, 04, 07, 09, 11 e 12 mais `voiceflux-audit-manifest.json`.

## Mapa de rotas

| Método         | Rota                           | Autorização                     | Consulta de inquilino indexado                                      |
| -------------- | ------------------------------ | ------------------------------- | ------------------------------------------------------------------- |
| `GET/PATCH`    | `/api/voiceflux/settings`      | leia união / `billing.manage`   | único `organizationId`                                              |
| `GET/POST`     | `/api/voiceflux/profiles`      | `agents.read` / `agents.write`  | `organizationId, enabled, createdAt`                                |
| `PATCH/DELETE` | `/api/voiceflux/profiles/[id]` | `agents.write`                  | direto `id` mais isolamento `organizationId`                        |
| `GET`          | `/api/voiceflux/usage`         | `billing.read` ou `agents.read` | `organizationId, periodEnd`                                         |
| `GET`          | `/api/voiceflux/jobs`          | `logs.read`                     | direto `conversationId, createdAt` mais isolamento `organizationId` |

Todos os IDs de perfil e de agente fornecidos pelos clientes são revalidados na organização ativa. Os diagnósticos de trabalho selecionam apenas status, metadados de provedor/modelo, contagens de tentativas, duração, código de falha segura e carimbos de data/hora. Eles nunca retornam texto de mensagem, `failureDetail`, `audioStorageKey` ou `audioUrl`.

`VoiceFluxSettingsUpdateSchema` exclui intencionalmente `includedAudioSeconds`; os inquilinos não podem conceder-se subsídio de provedor.

## Persistência

Modelos principais:

* `OrganizationVoiceFluxSettings`: ativação de direitos, estado da assinatura Stripe, perfil padrão, retenção, subsídio incluído.
* `VoiceFluxProfile`: estilo estruturado com escopo de organização/agente.
* `VoiceFluxSynthesisJob`: ciclo de vida idempotente e diagnóstico seguro.
* `VoiceFluxUsagePeriod`: UTC mensalmente incluído, comprado e usado segundos de áudio.

Os campos de ativação são `Agent.voiceRepliesEnabled` e `Conversation.voiceFluxEnabled`. A fila requer ambos os campos mais `Conversation.isAiEnabled`.

A resolução de perfil executa consultas indexadas separadas e aplica `agent profile > organization default > built-in defaults`. Não substitua filtros diretos `organizationId`, `agentId`, `conversationId` ou `messageId` por filtros de relação.

## Fluxo de tempo de execução

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.

Os canais de entrega suportados são Baileys, WhatsApp Cloud, Telegram `sendVoice`, anexo de áudio do Messenger e anexo de áudio do Instagram.

## Política de modelo fixo

As constantes de back-end são codificadas e não podem ser configuradas pelo locatário ou pelo ambiente:

```text theme={null}
attempt 1: gemini-3.1-flash-tts-preview
attempt 2: gemini-3.1-flash-tts-preview
recovery:  gemini-2.5-flash-tts (only after both 3.1 failures)
```

`gemini-3.1-flash-tts-preview` é tratado como estável e operacional e é a única linha de base de preço/capacidade. Nenhuma ramificação além dos dois IDs listados acima é permitida. As alterações exigem a atualização do pacote de auditoria `docs/voiceflux` completo e dos testes de política do provedor.

## Medição e retenção

A duração é medida a partir da saída OGG/Opus gerada e arredondada para um segundo inteiro. `meterVoiceFluxAudioSeconds` usa uma transação e `updateMany` condicional para reservar subsídio atomicamente. O consumo do provedor ainda será medido se a síntese for concluída após outra solicitação simultânea esgotar o limite de entrega.

Os objetos carregados recebem `expiresAt`. O trabalhador VoiceFlux verifica a coluna de expiração indexada a cada hora, exclui até 100 objetos S3 expirados por lote e limpa referências de armazenamento. A configuração de armazenamento ausente desativa a limpeza sem excluir registros de auditoria de trabalho.

## Faturamento e Stripe

VoiceFlux é um módulo de crescimento `level_2+`. O Checkout copia `organizationId` e `growthModuleKey` nos metadados da assinatura. Os eventos de conclusão de checkout e webhook de assinatura sincronizam a lista de módulos de assinatura base e `OrganizationVoiceFluxSettings.stripeSubscriptionId/status`. Assinaturas de complementos inativas ou excluídas desativam o VoiceFlux da organização.

O webhook continua sendo a fonte comercial da verdade. A UI não pode ativar o VoiceFlux quando a elegibilidade do plano ou o estado do complemento estão ausentes.

## Contrato de front-end

Alvos de dramaturgo obrigatórios:

| Superfície                                                 | Seletor                           |
| ---------------------------------------------------------- | --------------------------------- |
| Registros de conversa abaixo de ativação/desativação de IA | `logs-voiceflux`                  |
| Configurações existentes de funcionários de IA             | `agent-settings-voiceflux`        |
| Novo modal AI Employee                                     | `new-agent-voiceflux`             |
| Editor de perfil de voz do agente                          | `agent-voiceflux-profile`         |
| Configurações da organização                               | `voiceflux-organization-settings` |
| Último diagnóstico de conversa segura                      | `logs-voiceflux-diagnostic`       |

## Pegadinhas

* Nunca suprima a resposta de texto normal, a menos que o trabalho do VoiceFlux tenha sido enfileirado com sucesso.
* Nunca registre texto de resposta bruto, credenciais, cargas de provedor, URLs de áudio ou detalhes de erros internos.
* Não tente novamente os trabalhos de síntese do BullMQ independentemente do adaptador do provedor; o adaptador possui o teto exato da tentativa de modelo.
* Não exponha os IDs dos modelos como configurações do produto.
* Não adicione gravações permitidas ao esquema de configurações públicas.
* Mantenha o tratamento de cancelamento do Stripe sincronizado com a ativação da organização.

## Verificação

Execute os pacotes VoiceFlux Jest, verificações de tipo de painel/worker/lib, verificações práticas do Playwright para todos os seletores necessários, validação Prisma, scripts de tradução/navegação de documentos e, finalmente, a atualização forçada necessária do Graphify.