conversapp

Nó do n8n para o Conversapp: contatos, negócios, mensagens, conversas e fluxos pela API pública.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0
Author: Conversapp

Documentation

n8n-nodes-conversapp

O nó do Conversapp para o n8n: contatos, negócios, mensagens, conversas e fluxos, pela API pública (/v1) da sua conta.

  • Uma credencial (endereço da API + chave) e um nó com seis recursos: Contato, Negócio, Mensagem, Conversa, Fluxo e Conta (as listas de apoio: canais, etiquetas, funis e etapas, equipes, pessoas, modelos, motivos, campos personalizados).
  • Tudo em português. Onde o campo é "um canal", "uma etiqueta", "um funil", "uma etapa", "uma pessoa", "uma equipe" ou "um modelo", o nó mostra a lista da sua conta (pelo nome), em vez de pedir para colar um id.
  • Feito para repetir sem duplicar: a nova tentativa do próprio n8n não manda a mensagem duas vezes (veja Idempotência).

Provado no n8n 2.46.7 (imagem n8nio/n8n:2.46.7), contra a API do Conversapp. Se você usa outra versão, o nó deve funcionar do mesmo jeito (ele só usa o que o n8n entrega para nós da comunidade), mas essa é a que foi testada.

Instalação

Pela interface do n8n (instalação própria, não a n8n Cloud):

  1. Settings → Community Nodes → Install.
  2. Digite n8n-nodes-conversapp, aceite o aviso sobre nós da comunidade e clique em Install.

À mão, na pasta do n8n (~/.n8n/nodes):

cd ~/.n8n/nodes
npm install n8n-nodes-conversapp

Reinicie o n8n. O nó Conversapp aparece na busca de nós.

Criar a credencial

No Conversapp, abra Configurações → API:

  1. Crie uma chave (começa com sk_live_) e marque as permissões que o seu fluxo precisa (veja a tabela abaixo). A permissão é escolhida ao gerar a chave e não muda depois; para outra permissão, crie outra chave.
  2. Copie o Base URL da API que a tela mostra.

No n8n, crie a credencial Conversapp API:

Campo O que colocar
Endereço da API O «Base URL da API». Pode vir com ou sem /v1 no fim, com ou sem barra: o nó normaliza e nunca duplica o /v1.
Chave da API A chave sk_live_….

O endereço precisa começar com https://. http:// só vale para uma máquina local (localhost, 127.0.0.1, [::1] e host.docker.internal): a chave viaja em cabeçalho, e em http:// ela iria em texto puro. Qualquer outro http:// é recusado na credencial e em cada chamada. «Custom API Call» e nó HTTP Request. Por padrão a credencial vem com Domínios permitidos no nó HTTP Request = Nenhum: o «Custom API Call» (que o n8n acrescenta a toda credencial com autenticação) e o nó HTTP Request não conseguem usar a sua chave — as ações do nó Conversapp não são afetadas. Para liberar, na credencial escolha Domínios específicos e informe só o domínio da sua API (por exemplo, api.suaempresa.com.br).

O botão Test da credencial chama GET /v1/channels?limit=1, que pede só a permissão de leitura.

O que cada recurso faz e a permissão que pede

Recurso Ações Permissão da chave
Contato Criar · Obter · Buscar por telefone · Listar · Atualizar · Atualizar pelo telefone · Criar ou atualizar pelo telefone · Excluir · Etiquetar · Tirar etiqueta Ler dados · Criar e editar contatos · Excluir contatos
Negócio Criar · Obter · Listar · Atualizar · Mover de etapa · Ganhar · Perder · Duplicar · Excluir · Definir responsáveis · Etiquetar · Tirar etiqueta · Notas (criar, listar, atualizar, excluir) Ler dados · Criar e editar negócios · Excluir negócios · Escrever notas internas
Mensagem Enviar texto · Enviar modelo · Enviar mídia · Consultar estado Enviar e agendar mensagens (mídia pede também Enviar arquivos e mídia; consultar o estado pede Ler conversas e mensagens)
Conversa Listar · Obter · Listar mensagens · Atribuir a uma pessoa · Transferir para uma equipe · Arquivar · Desarquivar · Notas (criar, listar, atualizar, excluir) Ler conversas e mensagens · Atender conversas · Escrever notas internas
Fluxo Listar fluxos · Iniciar para um · Iniciar em lote · Consultar execução Iniciar fluxos
Conta Listar canais, etiquetas, funis e etapas, equipes, pessoas, modelos, motivos de arquivamento e de perda, campos personalizados (do contato e de um funil) Ler dados (a lista de modelos pede Enviar e agendar mensagens)

A permissão exata de cada ação está na página da rota, na referência da API.

Sem a permissão, a API responde 403 com a frase que diz qual falta; o nó mostra essa frase.

Exemplos

Cinco workflows prontos para importar (Workflows → Import from File) estão na pasta exemplos/ do pacote. Todos usam a credencial sem valor (escolha a sua) e dados de mentira (5511900000000 é um telefone fictício). Troque os campos de lista (canal, funil, etapa…) pelos da sua conta antes de executar.

Arquivo O que faz
contato-criar-e-etiquetar.json Contato: cria ou atualiza pelo telefone e põe uma etiqueta.
negocio-criar-e-mover.json Negócio: cria num funil e move de etapa.
mensagem-enviar-por-telefone.json Mensagem: envia um texto para um telefone (a rota cria o contato e a conversa na mesma chamada).
conversa-atribuir-e-arquivar.json Conversa: atribui a uma pessoa e arquiva (sem motivo, a API usa «Encerrada por integração»).
fluxo-iniciar-em-lote.json Fluxo: inicia um fluxo para vários contatos (o nó divide em lotes de 50).

Mensagens: as três formas de endereçar, modelo e mídia

  • Enviar para: Telefone (com o canal; a rota cria o contato e a conversa se não existirem; dá para informar o nome, a equipe e o responsável do contato novo), Contato (o id e o canal) ou Conversa (o id).
  • Enviar modelo: escolha o modelo (só os aprovados aparecem) e as variáveis do corpo como lista ({{1}}, {{2}}…) ou por nome ({{nome}}); há campos para a variável do cabeçalho e a do botão de link.
  • Enviar mídia: o arquivo vem do binário do item (o nó guarda na API e envia), de um endereço (a API baixa uma vez) ou de um id de arquivo já guardado. Legenda opcional.
  • A resposta do nó é a mensagem com estado pending: o envio ao WhatsApp é assíncrono. Para saber se foi entregue, use Mensagem → Consultar estado com o id devolvido (ou os webhooks do Conversapp).

Retornar todos e a varredura incremental

As listagens têm Retornar todos (lê páginas de 100 até o fim) ou Limite (padrão 50, no máximo 500). Para proteger a memória do n8n, o teto é de 10.000 itens: acima disso o nó para e avisa — «Foram lidos 10.000 itens; refine com os filtros (por exemplo, "Atualizados desde") para ler o resto.» — em vez de devolver metade como se fosse tudo.

Para ler só o que mudou desde a última vez, use o filtro Atualizados desde, ordene por Última atualização (crescente), leia sempre a primeira página e avance a marca. Não percorra page=2, 3… num mesmo passe: as linhas mudam de posição enquanto você lê. O nó expõe o filtro; guardar a marca entre execuções é do seu workflow.

Idempotência e «Retry On Fail»

As rotas que criam algo (contato, negócio, nota, mensagem, início de fluxo, cópia de negócio) aceitam o cabeçalho Idempotency-Key: a mesma chave com o mesmo corpo, em até 24 horas, devolve a resposta guardada em vez de repetir o efeito. O nó manda uma chave por conta própria, derivada de execução + nó + execução do nó + item (e do lote, no início de fluxo em lote). Assim, se você ligar Settings → Retry On Fail no nó e a primeira tentativa falhar no meio do caminho, a nova tentativa usa a mesma chave e a mensagem não sai duas vezes. Uma execução nova do workflow é outra chave. Para controlar você mesmo, escreva a sua em Opções → Chave de idempotência (de 1 a 255 caracteres visíveis).

Limite de chamadas (429) e erros

  • 429: o nó espera o tempo de Retry-After (sem o cabeçalho, 1 s, 2 s, 4 s; nunca mais de um minuto por espera) e repete, até 3 novas tentativas; depois vira erro. Vale para qualquer ação, porque 429 significa que nada foi feito.
  • 5xx e erro de rede não são repetidos pelo nó: use Retry On Fail (a chave estável protege contra duplicar).
  • Todo erro da API aparece como [código] mensagem (sem código, só a mensagem), com o status HTTP na descrição. Com Continue On Fail ligado, o item sai com { "error": { "statusCode", "code", "message" } }.
  • A chave nunca aparece em mensagem de erro, no log nem no JSON do item.

Campos personalizados

Em Contato e Negócio (criar, atualizar), o grupo Campos personalizados deixa escolher o campo da sua conta e o valor. O nó consulta o tipo do campo e manda o valor no formato certo (data como AAAA-MM-DD, campo de marcar como true/false, número com ponto decimal, lista de opções separada por vírgulas). Valor vazio limpa o campo. Em Campos adicionais → Campos personalizados (JSON) você pode escrever o objeto { "<id do campo>": valor }. Os campos do negócio dependem do funil: escolha o Funil antes.

O que o nó NÃO faz

  • Não tem gatilho: receber eventos do Conversapp no n8n (webhooks) é a próxima etapa.
  • Não converte workflows de outros nós.
  • Não faz lote de contatos, disparos, mensagens agendadas, gestão de webhooks, convites, pessoas e equipes, horário comercial, links de acesso, edição ou exclusão de mensagem, nem gerencia arquivos além de guardá-los para enviar.
  • Não é uma ferramenta de IA para agentes do n8n (usableAsTool desligado de propósito: um agente enviando mensagem a cliente sem ninguém ver não é um padrão de nó).

O sentido contrário

Para o Fluxo do Conversapp chamar um workflow do n8n e esperar a resposta, use o bloco «Requisição HTTP (API)» do construtor de Fluxos: veja o guia «Fluxo do Conversapp chamando o n8n» no manual da API.

Licença

MIT. O n8n-workflow é dependência de pares: vem do seu n8n, nunca embutido neste pacote.

Discussion