📙 Manual Interno 03: Automação Low-Code com n8n & Node Nvoip

🛡️ Sentinel Status

  • Classificação: Manual de Automação & Workflows Operacionais
  • Componente Principal: @nvoip/n8n-nodes-nvoip
  • Ambiente: Servidor n8n (Docker / Self-hosted / Cloud)
  • Pacote Local de Referência: D:\ai-projects\_nvoip\nvoip-n8n\

1. Visão Geral do Node @nvoip/n8n-nodes-nvoip

O node da comunidade oficial da Nvoip para n8n permite orquestrar operações de telecomunicações sem necessidade de programação manual de endpoints REST. O node implementa chamadas telefônicas, envio de SMS, notificações oficiais de WhatsApp Business e disparos de Torpedo de Voz com síntese TTS.

flowchart TD
    A[Gatilho: Formulário / Webhook / CRM] --> B{Node Nvoip n8n}
    B -->|Canal 1| C[WhatsApp HSM Template]
    B -->|Canal 2: Fallback| D[SMS Corporativo]
    B -->|Canal 3: Voz| E[Click-to-Call / Torpedo TTS]
    C --> F[Log no Banco / Airtable / Supabase]
    D --> F
    E --> F

2. Instalação e Configuração no n8n

2.1. Instalação via Interface Web do n8n

  1. No menu lateral do seu n8n, acesse Settings > Community Nodes.
  2. Clique no botão Install a community node.
  3. No campo npm Package Name, digite: 
    @nvoip/n8n-nodes-nvoip
  4. Aceite os termos de uso de nós da comunidade e confirme a instalação.

2.2. Configuração de Credenciais

  1. No menu Credentials, clique em New Credential e pesquise por Nvoip Access Token API.
  2. Preencha os campos obrigatórios:
    • Client ID: Seu identificador de cliente Nvoip.
    • Client Secret: Sua chave secreta de API.
    • User Sip: Seu ramal SIP principal (ex: 68105001).
  3. Clique em Save & Test Connection.

3. Workflows Prontos de Produção

No repositório local D:\ai-projects\_nvoip\nvoip-n8n\docs\workflows\, estão disponíveis três fluxos prontos para importação direta no n8n:

3.1. Workflow 01: Callback Imediato de Vendas (callback_vendas.json)

Objetivo: Reduzir o tempo de resposta a leads para menos de 60 segundos.

[Webhook Novo Lead] ➔ [Tratar Telefone] ➔ [Node Nvoip: Make Call] ➔ [Registrar no CRM]
  • Funcionamento: Quando um visitante preenche um formulário no portal Artes do Sul ou em landing pages, o webhook aciona o node Nvoip.
  • O sistema primeiro faz o ramal do atendente tocar. Assim que o atendente atende, o PABX disca imediatamente para o lead, conectando as duas pontas sem esforço manual.

3.2. Workflow 02: Notificação Multicanal com Fallback (notificacao_multicanal.json)

Objetivo: Garantir a entrega de avisos críticos (status de chamado, confirmação de pedido, alertas de sistema).

[Evento de Alerta] ➔ [Node Nvoip: WhatsApp Template] ➔ [Verificar Status Entrega]
                                                               ├── Sucesso ➔ [Fim]
                                                               └── Falha / Sem WA ➔ [Node Nvoip: Enviar SMS]
  • Funcionamento: Tenta o envio prioritário via WhatsApp Business Platform utilizando HSM homologado.
  • Caso o número não possua WhatsApp ativo ou retorne erro transitório, o nó de decisão automaticamente redireciona o payload para o envio de SMS corporativo.

3.3. Workflow 03: Pesquisa de Satisfação por Voz com DTMF (pesquisa_satisfacao.json)

Objetivo: Realizar pesquisa NPS automática após a conclusão de chamados de suporte técnico.

[Chamado Fechado no Suporte] ➔ [Delay 10 Min] ➔ [Node Nvoip: Torpedo Interativo DTMF] ➔ [Capturar Nota 1-5] ➔ [Atualizar Ticket]
  • Funcionamento: O PABX dispara um Torpedo de Voz programado com a mensagem:

    “Olá! O estúdio Artes do Sul agradece seu contato. Em uma escala de 1 a 5, como você avalia o atendimento recebido?”

  • O dígito pressionado no teclado do celular é capturado e enviado de volta ao webhook do n8n para atualizar a nota de satisfação no painel administrativo.

4. Boas Práticas e Governança de Custos

  1. Validação E.164 Prévia: Sempre normalize os números de telefone antes de passar ao nó Nvoip (ex: remover caracteres como parênteses e traços, garantindo formato 55 + DDD + Número).
  2. Rate Limiting: Em envios de SMS e Torpedo em lote, utilize nós de Split in Batches com intervalo de 200ms a 500ms entre requisições para evitar throttling na API.
  3. Mecanismo Circuit Breaker: Se o saldo da conta Nvoip cair abaixo de R$ 50,00, configure um nó condicional no n8n para emitir alerta interno no Telegram ou Slack antes de interromper os fluxos.