> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/whatsapp-api-hyperflow/integracao-via-n8n.md).

# Integração via n8n

Utilize este guia para configurar nosso Community Node no n8n e automatizar suas interações via WhatsApp.

### O que este pacote oferece

Concluída a instalação, o n8n disponibilizará dois novos módulos em sua biblioteca de nós:

<table><thead><tr><th width="302.44921875">Nó</th><th>Função</th></tr></thead><tbody><tr><td><strong>Hyperflow WhatsApp</strong></td><td>Envia mensagens (texto, mídia, listas, templates HSM, catálogo, flows, etc.).</td></tr><tr><td><strong>Hyperflow WhatsApp Trigger</strong></td><td>Inicia fluxos quando ocorrem eventos do WhatsApp (mensagem recebida, status, botão, lista, resposta de flow).</td></tr></tbody></table>

### Instalação

{% hint style="info" %}
No momento, o ***Community Node*** está disponível exclusivamente para versões **Self-hosted** do n8n (não sendo compatível com o n8n Cloud). A instalação pode ser realizada diretamente pelo painel administrativo ou via terminal. Para detalhes técnicos sobre os métodos de instalação, consulte a [Install and manage community nodes](https://docs.n8n.io/integrations/community-nodes/installation/).
{% endhint %}

**Instalação via Interface**

1. **Acesso:** Faça login no n8n com privilégios de administrador.
2. **Navegação:** Vá em **Settings** > **Community Nodes**.
3. **Instalação:** Selecione a opção para instalar um novo nó e insira o nome oficial do pacote: `@hyperflow-global/n8n-nodes-hyperflow-whatsapp`
4. **Finalização:** Caso solicitado pelo seu ambiente, reinicie a instância do n8n para aplicar as alterações.

### Autenticação

#### Configuração de Autenticação

A comunicação com a API é protegida e exige uma API Key. Siga os passos abaixo para obter e configurar sua credencial:

1. **Obter a Chave:** Acesse o [Painel de Integrações](https://integracoes.hyperflow.global/whatsapp), selecione a conta de WhatsApp desejada e clique em Editar.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FUTGUCLvaJHIADHd55FH1%2Fimage.png?alt=media&amp;token=22dce0f7-f55a-47bd-9411-9eed682e8b69" alt=""><figcaption><p>Imagem 1 - Editando contas do WhatsApp no Hyperflow integrações.</p></figcaption></figure>

2. **Visualizar:** Clique no ícone de visualização (olho) para exibir a API Key completa e copie o código.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FpvFP0o4I6lR0UbQh2z0U%2Fimage(1).png?alt=media&amp;token=33a7dc82-651a-4eca-ad41-efa90ab72a24" alt=""><figcaption><p>Imagem 2 - Obtenção do token da conta de WhatsApp desejada.</p></figcaption></figure>

3. o seu workflow do n8n, acesse o campo 'Credential to connect with' e insira o token em qualquer um dos módulos. Ao configurar a credencial em um deles, ela será aplicada automaticamente ao outro módulo da integração.
   * Hyperflow WhatsApp (para envio de mensagens).
   * Hyperflow WhatsApp Trigger (para recebimento de eventos).

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FOTJr5tVkgOZkZOuoXLMm%2Fimage(3).png?alt=media&amp;token=2baa63d2-397a-484b-890f-9e41e2f60257" alt=""><figcaption><p>Imagem 3 - Configuração parcial do n8n</p></figcaption></figure>

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FxL7AzAyjzIDBCW6NcXUB%2Fimage(4).png?alt=media&amp;token=4bc07400-3838-41d6-936c-2d7882a9ff3e" alt=""><figcaption><p>Imagem 4 - Inserção da chave de API obtida da conta do WhatsApp</p></figcaption></figure>

4. Não esqueça de configurar a **Webhook URL** no campo correspondente para habilitar o recebimento de mensagens em tempo real.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2F8FN9Iz0GKzVtB1pYkNYP%2Fimage(5).png?alt=media&amp;token=fdbe36cb-bc26-445d-80e8-1709d665ea99" alt=""><figcaption><p>Imagem 5 - Configuração do Webhook para recebimento de mensagens em tempo real.</p></figcaption></figure>

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FZ45mkcLMqcPUH0JVvR0z%2Fimage(6).png?alt=media&amp;token=feafc6f6-9090-46d4-9213-44505f848392" alt=""><figcaption><p>Imagem 6 - URLs geradas serão vinculadas nesses campos setados.</p></figcaption></figure>

### Utilização dos nodes

{% file src="/files/XsrbulFkwrzBUnn2T1YT" %}

Para mostragem foi feito um workflow simples:

1. Adicionado o node ***Hyperflow WhatsApp Trigger*** para iniciar um workflow quando eu receber uma mensagem no número WhatsApp que configurei anteriormente;
2. Adicionado um node ***AI Agent*** para comunicar um modelo IA;
3. Adicionado o node ***Hyperflow WhatsApp*** para me devolver via mensagem de WhatsApp o que o meu modelo respondeu.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FtkvH9CfDSDKr9f230cOM%2Fimage.png?alt=media&amp;token=6ba49c0c-564c-4fcf-b064-15947da66b67" alt=""><figcaption><p>Imagem 7 - Exemplo de configuração no n8n</p></figcaption></figure>

Para iniciar a conversa, acesse a tela **WhatsApp Accounts** onde temos um link de conversa com WhatsApp para configuração do proxy do número que estaremos utilizando, envie a mensagem de proxy e ele já estará conectado ao seu workflow:

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2Fk9qlYj6S4tLlRpGXroqS%2Fimage(7).png?alt=media&amp;token=6172f049-55d8-429e-8842-6f59287f6bc3" alt=""><figcaption><p>Imagem 8 - Onde pegar o numero de teste da conta do WhatsApp sendo configurada</p></figcaption></figure>

Para iniciar a conversa, clique no link mencionado e envie a mensagem pré-configurada (ex: `proxy AULEU8JW`). A partir disso, o chat é ativado, permitindo interagir com a IA no n8n ou executar fluxos personalizados conforme as definições no painel de Integrações Hyperflow.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2F2i1qmlOcMjEipM0Easjx%2Fimage.png?alt=media&amp;token=232379a3-5636-4021-897f-6d87974b5676" alt=""><figcaption><p>Imagem 9 - Envio de mensagem teste 'proxy AULEU8JW' para testar conversa</p></figcaption></figure>

E visualizando a configuração dentro do nosso workflow, node por node:

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FP8qUs0usAUao67RbgG97%2Fimage.png?alt=media&amp;token=cafc0135-d16d-47b7-b491-0b4b5052ba43" alt=""><figcaption><p>Imagem 10 - Visualização do output de pergunta recebida</p></figcaption></figure>

E por fim a visualização da resposta obtida no output.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FgQXqb1TJxHv938gZDkV5%2Fimage(8).png?alt=media&amp;token=bf5f3b89-342d-4cdd-9411-d8db5cca7075" alt=""><figcaption><p>Imagem 11 - Visualização do output de resposta enviada</p></figcaption></figure>

{% hint style="success" %}
Sucesso! Agora sua conta WhatsApp está conectada a um workflow do n8n!
{% endhint %}