Package Information
Available Nodes
Documentation generating…
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):
- Settings → Community Nodes → Install.
- 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:
- 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. - 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
ide o canal) ou Conversa (oid). - 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 oiddevolvido (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 (
usableAsTooldesligado 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.