Skip to main content
#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

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:
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:

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