12 ações do node UnderChat no n8n: usos e exemplos

O node oficial da UnderChat reúne no n8n ações específicas para contatos, atendimentos, mensagens, horários e consultas operacionais. A questão prática não é apenas saber que elas existem, mas escolher qual ação corresponde ao identificador e ao resultado que o workflow já possui: telefone ou Chat ID, cadastro ou atendimento, setor fixo ou destino obtido durante o fluxo.

Este artigo se concentra na escolha das ações e nos exemplos visíveis nas cinco telas reais abaixo. Aqui, partimos do node já disponível no editor e avançamos diretamente para suas funcionalidades.

Para transformar tarefas repetitivas em uma jornada organizada, conheça o chatbot para WhatsApp da UnderChat, que combina automação, inteligência artificial e transferência para atendimento humano.

Precisa instalar o node? Este artigo parte do node já disponível no editor. Para adicionar o pacote ao n8n, use a documentação oficial:

Abrir passo a passo de instalação na Wiki →

Em resumo: a tela de detalhes fornecida para esta análise apresenta 12 ações. Elas cobrem o início e a transferência de atendimentos, cadastro e localização de contatos, consulta de horário de funcionamento, listagens de apoio e três formas de envio de mensagem.

As funcionalidades do node em cinco telas reais

A galeria mostra o painel de ações, o seletor de recursos, um workflow com Google Sheets e duas configurações concretas: envio por telefone e transferência para um setor. Clique em uma imagem para ampliá-la. Os campos vazios e alertas fazem parte das telas antes da execução; as capturas não representam, por si só, um teste concluído.

Mapa das 12 ações: qual problema cada uma resolve

A tabela reproduz as ações nomeadas na tela fornecida. A indicação de uso parte do próprio nome de cada operação e dos campos efetivamente visíveis, sem presumir respostas ou parâmetros não mostrados.

O seletor também exibe Custom API Call. Como as capturas não revelam seus parâmetros nem seu retorno, ele não foi incluído entre os 12 itens descritos e nenhuma capacidade adicional é atribuída a esse recurso aqui.

Como escolher a ação certa sem misturar identificadores

Você tem o telefone, mas não o Chat ID

Há três decisões diferentes que podem começar pelo telefone:

• Obter a referência do contato: use Buscar ID do contato pelo telefone quando a próxima etapa depende desse identificador.
• Enviar conteúdo diretamente ao número: use Enviar mensagem por telefone quando essa é a operação desejada.
• Localizar ou criar a pessoa e iniciar um atendimento: selecione a ação combinada quando o objetivo inclui o começo do atendimento, não apenas o cadastro.

Essas operações não são intercambiáveis. A escolha deve partir do resultado necessário, e não apenas do dado disponível na entrada.

Você já tem o Chat ID

O Chat ID aparece como referência em duas situações visíveis: envio de mensagem por conversa e transferência do chat. Se o objetivo é comunicar algo dentro da conversa identificada, a ação de mensagem por Chat ID é a opção relacionada. Se o objetivo é mudar a responsabilidade pelo atendimento, a ação de transferência acrescenta a escolha entre setor e usuário.

Você só precisa cadastrar o contato

Criar contato atende a uma intenção mais restrita do que Buscar ou criar contato e iniciar atendimento. Prefira a ação simples quando o workflow deve apenas registrar a pessoa. Use a ação combinada quando o resultado desejado inclui explicitamente iniciar o atendimento.

O destino não deve ficar fixo no workflow

As ações de listar executores, setores e usuários oferecem pontos próprios de consulta. Elas podem apoiar uma seleção posterior sem depender de um valor digitado manualmente. Antes de montar essa combinação, execute a listagem isoladamente e confirme a estrutura efetivamente retornada; as telas fornecidas demonstram a existência das ações, mas não mostram seus dados de saída.

O comportamento depende do expediente

A ação Verificar dias e horas de funcionamento pode ser posicionada antes de uma decisão relacionada ao horário. Como o retorno não aparece nas capturas, teste a operação separadamente e somente depois construa condições com os campos observados na execução real.

Exemplo 1: processar contatos de uma planilha

A captura horizontal mostra um fluxo com acionamento manual, leitura de linhas no Google Sheets, um loop, a ação Buscar ou criar contato e iniciar atendimento e uma atualização posterior da planilha. Esse encadeamento ilustra um caso de uso objetivo: processar cada registro e deixar uma etapa final para registrar o que ocorreu.

Ao adaptar a ideia, defina explicitamente:

1. qual coluna contém o telefone e se o DDI já está presente;
2. quais campos alimentam a busca ou a criação do contato;
3. qual informação da execução deve ser gravada na planilha;
4. como impedir que uma linha já processada seja tratada novamente;
5. quantos registros serão usados no primeiro teste controlado.

A imagem não expõe os mapeamentos nem a saída das etapas. Portanto, ela serve como referência de sequência, não como um workflow pronto para copiar sem validação.

Exemplo 2: enviar mensagem a partir de um telefone

Na tela correspondente, o recurso selecionado é Mensagem e a operação é Enviar Mensagem Por Telefone. Os campos visíveis permitem revisar o contexto antes da execução:

• credencial da conta UnderChat;
• executor;
• DDI e telefone;
• nome para novo contato;
• canal e setor;
• controle Criar Se Não Existir;
• tipo de conteúdo, mostrado como mensagem de texto no exemplo;
• mensagem e campos adicionais em JSON.

Na captura, o DDI exibido é 55, o controle de criação está ativo e alguns campos permanecem vazios, acompanhados por alertas. O valor mostrado é apenas parte daquele exemplo. Antes de executar, revise se telefone, executor, canal e setor pertencem ao mesmo contexto operacional e valide qualquer JSON adicional.

Exemplo 3: transferir uma conversa para o setor correto

A tela de transferência usa o recurso Atendimento e a operação Transferir Para Setor Ou Usuário. No exemplo visual, o tipo de destino é Setor e o destino selecionado é Financeiro.

A configuração exibida reúne executor, tipo de destino, setor, Chat ID, anotação e controles relacionados à entrada no atendimento, permanência do executor no chat e mensagem automática. Alguns rótulos aparecem cortados na captura; por isso, leia os textos completos no seu ambiente antes de mudar qualquer controle.

Uma regra segura para essa ação é separar três decisões:

1. Qual conversa? forneça o Chat ID correspondente ao atendimento esperado.
2. Qual tipo de destino? escolha setor ou usuário.
3. Qual destino específico? selecione um item compatível com o tipo definido.

Mais quatro combinações úteis das ações disponíveis

Localizar o contato antes de uma ação baseada em ID

Quando a entrada contém apenas o telefone, Buscar ID do contato pelo telefone pode anteceder uma etapa que exija o identificador do contato. Confirme o formato do telefone e observe a saída real antes de mapear o próximo node.

Consultar setores antes de definir uma transferência

Listar setores e Transferir chat para setor ou usuário são ações distintas que podem participar do mesmo processo. A primeira consulta opções; a segunda realiza o encaminhamento. Se houver uma regra de escolha entre destinos, trate-a em uma etapa explícita e teste com conversas controladas.

Separar consulta de horário e decisão de rota

Use a verificação de dias e horas como fonte para uma decisão posterior, sem presumir o formato do retorno. Depois de examinar o resultado, o workflow pode encaminhar cada caminho para as etapas adequadas ao processo definido pela empresa.

Enviar por telefone ou por conversa

As duas ações de mensagem resolvem entradas diferentes. Quando o número é a referência disponível, a operação por telefone expõe DDI, telefone e opções de criação do contato. Quando a conversa já foi identificada por Chat ID, use a ação correspondente a esse identificador. Evite converter um em outro sem uma etapa clara de busca e validação.

Matriz rápida de decisão

Checklist antes de executar um fluxo com o node

1. Defina o resultado de negócio daquela etapa em uma frase.
2. Confirme se a entrada disponível é telefone, ID do contato ou Chat ID.
3. Escolha uma operação compatível com esse identificador e com o resultado esperado.
4. Revise credencial, executor, canal, setor e destino quando esses campos aparecerem.
5. Decida conscientemente se o contato deve ser criado quando não existir.
6. Valide o formato de qualquer conteúdo adicional em JSON.
7. Execute uma operação isolada com dados controlados.
8. Examine a saída real antes de mapear o node seguinte.
9. Só depois amplie para loops, planilhas ou volumes maiores.

Esse checklist não substitui regras próprias do processo. Ele reduz principalmente dois erros de configuração: usar uma ação que devolve um resultado diferente do necessário e tratar telefone, contato e conversa como se fossem o mesmo identificador.

Do node isolado ao fluxo que a equipe realmente usa

As 12 ações formam peças específicas. Um bom primeiro caso de uso combina uma entrada conhecida, uma única ação da UnderChat e um registro verificável do resultado. Depois de validar os campos e a saída, o fluxo pode evoluir para consultas, decisões e encaminhamentos mais completos.

Se a operação precisa conectar automação, atendimento humano e organização de conversas, conheça a plataforma UnderChat.