Um utilizador preencheu um formulário, clicou em «Submeter» e não aconteceu nada. A página recarregou, os campos foram limpos, mas não ficou claro se o email foi realmente enviado.

O Contact Form 7 não mostra notificações visuais após o envio na sua configuração de origem. As mensagens de sucesso ou erro ficam escondidas abaixo do formulário, em texto pequeno, sem animação, sem destaque. Os utilizadores simplesmente não reparam nelas e saem sem saber se o seu envio foi recebido.

Pode resolver isto em 10 minutos. Só precisa do Contact Form 7, de qualquer plugin de popup com uma API de JavaScript e de 25 linhas de código. O resultado: após o envio do formulário, uma janela grande aparece suavemente sobre a página (verde para sucesso, vermelha para erro) e desaparece automaticamente após um intervalo definido. Sem recarregamento de página, sem perda de contactos.

💡 Visão geral rápida:

• Que eventos DOM o Contact Form 7 dispara e como os nomes modernos diferem dos legados
• Como criar popups de sucesso e erro em qualquer plugin de popup do WordPress
• Estilos CSS para popups: overlay, animação, z-index
• Um script jQuery pronto a usar: associação dos eventos do CF7 à abertura e fecho automático do popup
• Uma alternativa moderna usando addEventListener sem jQuery
• Configurar a duração de exibição separadamente para sucesso e erro

Que eventos DOM o Contact Form 7 dispara

O Contact Form 7 gera eventos DOM personalizados em cada etapa do processamento do formulário. Aqui está a lista completa da documentação oficial:

Para popups pós-envio, precisa de dois eventos: wpcf7mailsent (sucesso) e wpcf7invalid (erro de validação). Também poderia usar o wpcf7spam para uma janela de aviso separada, mas, na prática, os dois primeiros são suficientes.

Nota importante: em guias e snippets mais antigos, os eventos são escritos com dois pontos. Por exemplo, wpcf7:mailsent e wpcf7:invalid. Esta sintaxe era usada nos hooks jQuery das versões anteriores do CF7. Hoje ainda funciona por retrocompatibilidade, mas os nomes canónicos não incluem os dois pontos. No código abaixo, fornecerei ambas as variantes: a moderna usando addEventListener e a variante jQuery para projetos onde o jQuery já está carregado.

O objeto event.detail contém propriedades úteis: contactFormId (o ID do formulário específico), pluginVersion (versão do CF7), inputs (array de dados introduzidos). Se tiver vários formulários numa página, filtre por contactFormId para que o popup abra apenas para o formulário pretendido.

Passo 1: escolha um plugin de popup e crie as janelas

Precisa de um plugin de popup com uma API JavaScript para que a janela possa ser aberta programaticamente a partir de um script. Duas opções gratuitas comprovadas do diretório de plugins do WordPress.org:

• Popup Maker, mais de 700.000 instalações ativas, classificação de 4,9/5. Chamada: PUM.open(popup_id). Núcleo gratuito poderoso, segmentação por página, acionadores de tempo e scroll, integração com formulários populares. A maior comunidade, onde encontrará respostas para qualquer dúvida.
• WP Popups, mais de 20.000 instalações ativas. Chamada: SPU.show(popup_id). Editor visual baseado em Gutenberg, filtros de exibição, suporte ao Contact Form 7 de origem. Leve e rápido.

Crie dois popups: um para envio bem-sucedido, outro para erros. Em cada um, coloque uma imagem, texto e, opcionalmente, um botão «Fechar». Anote o ID de cada janela, pois vai precisar deles no script do passo 3. Os exemplos abaixo usam os IDs 1068 (sucesso) e 1065 (erro); os seus serão diferentes.

Eis o aspeto dos popups com os estilos configurados:

Popup de envio bem-sucedido: fundo verde, ícone de confirmação e texto.

Janela de erro: fundo vermelho, ícone de aviso e um pedido para verificar os dados introduzidos.

E aqui estão as imagens para colocar dentro dos popups:

Pode substituir estas imagens pelas suas, especificando caminhos diferentes nas definições do plugin de popup.

Passo 2: estilos CSS para os popups

Popup plugins don't always export custom CSS. If styles aren't applied after creating the windows, add them manually: Plugin Settings → Custom CSS, or Appearance → Customize → Additional CSS.

Styles for the successful submission popup (green overlay, maximum z-index):

1
div#spu-bg-1068 {
2
    opacity: 0.6;
3
    background-color: green;
4
    z-index: 9999999;
5
}
6
div#spu-1068 {
7
    z-index: 99999999;
8
}

Styles for the error popup (red overlay):

1
div#spu-bg-1065 {
2
    opacity: 0.6;
3
    background-color: #F44336;
4
    z-index: 9999999;
5
}
6
div#spu-1065 {
7
    z-index: 99999999;
8
}

What's happening here: #spu-bg-N is the semi-transparent backdrop (overlay). #spu-N is the window itself. The high z-index ensures the popup covers all page elements, including the admin bar.

If you're using a different popup plugin, replace the selectors. Popup Maker generates #pum-N and .pum-overlay[data-popmake*="N"]. WP Popups uses its own prefixes; check the browser inspector (F12) for the actual IDs of your windows.

Step 3: jQuery script linking CF7 and popups

The script can be inserted in one of three ways: in your child theme's functions.php, via the Code Snippets plugin, or in your theme's custom JavaScript section. Before editing functions.php, make a backup; one syntax error will crash the site.

Below is the complete code with comments. It catches two Contact Form 7 events and calls the popup plugin API:

1
// START: Contact Form 7 + Popups — popups for success and error
2
jQuery(document).ready(function($) {
3
 
4
    // Popup for validation ERROR (fields empty or invalid)
5
    $(".wpcf7").on('wpcf7:invalid', function(event) {
6
        SPU.show(1065);   // Error popup ID — replace with yours
7
        setTimeout(function() {
8
            $('div#spu-1065, div#spu-bg-1065').fadeOut(600, 'swing');
9
        }, 5500);          // auto-close after 5.5 seconds
10
    });
11
 
12
    // Popup for SUCCESSFUL submission
13
    $(".wpcf7").on('wpcf7:mailsent', function(event) {
14
        SPU.show(1068);   // Success popup ID — replace with yours
15
        setTimeout(function() {
16
            $('div#spu-1068, div#spu-bg-1068').fadeOut(600, 'swing');
17
        }, 3500);          // auto-close after 3.5 seconds
18
    });
19
 
20
});
21
// END: Contact Form 7 + Popups

What you need to replace for your project:

• SPU.show(N) with your popup plugin's method. For Popup Maker: PUM.open(N).
• 1065 and 1068 with your popup IDs. Find them in the plugin's admin panel.
• Time in setTimeout (milliseconds). 5500 = 5.5 seconds, 3500 = 3.5 seconds. Adjust to your preference.
• Selectors div#spu-N and div#spu-bg-N; replace if your plugin generates different IDs.

Modern alternative without jQuery. If your theme doesn't load jQuery or you want a lighter option, use native CF7 events via addEventListener:

1
document.addEventListener('wpcf7mailsent', function(event) {
2
    // event.detail.contactFormId — ID of specific form (if there are multiple)
3
    PUM.open(1068);
4
    setTimeout(function() {
5
        document.querySelector('#pum-1068').style.display = 'none';
6
        document.querySelector('.pum-overlay[data-popmake*="1068"]').style.display = 'none';
7
    }, 3500);
8
}, false);
9
 
10
document.addEventListener('wpcf7invalid', function(event) {
11
    PUM.open(1065);
12
    setTimeout(function() {
13
        document.querySelector('#pum-1065').style.display = 'none';
14
        document.querySelector('.pum-overlay[data-popmake*="1065"]').style.display = 'none';
15
    }, 5500);
16
}, false);

This variant works with Popup Maker and doesn't require jQuery. The events wpcf7mailsent and wpcf7invalid (without the colon) are the modern standard.

If you have multiple forms on a page, filter by contactFormId:

1
document.addEventListener('wpcf7mailsent', function(event) {
2
    if ('123' === event.detail.contactFormId) {
3
        PUM.open(1068);  // popup only for form ID=123
4
    }
5
}, false);

Configuring auto-close timing

The interval for each popup is set separately using the second argument of setTimeout in milliseconds. Practical recommendations:

• Success: 3-5 seconds. The user has already read "sent," so there's no need to hold it longer.
• Error: 5-7 seconds. The person needs time to process the problem, re-read the message, and understand which fields to fix.
• Spam (wpcf7spam): 8-10 seconds. Give enough time to read the warning completely, but don't lock up the page entirely.

The value 600 in fadeOut(600, 'swing') is the fade-out animation duration in milliseconds. Less than 400 looks jerky, more than 800 feels slow. 600 is the sweet spot.

If you have multiple popups and want different durations for different forms, wrap the setTimeout call in a contactFormId check, as shown in the example above.

Step-by-step video tutorial: setting up a popup after Contact Form 7 submission from scratch. If you're new to WordPress or prefer watching over reading code, these 8 minutes of screen time cover half the article.

⁉️🤔 Perguntas frequentes

A popup não abre após o envio do formulário. O que está errado?

A causa mais comum: o ID da popup não corresponde ao especificado no script. Vá ao painel de administração do seu plugin de popups, encontre o ID real da janela e substitua-o na chamada SPU.show(N) ou PUM.open(N). A segunda causa: o jQuery não está carregado ou está em conflito. Verifique a consola do navegador (F12 → Consola) para ver erros. Os plugins de popups atribuem números novos às janelas durante a clonagem ou importação, enquanto o ID antigo do snippet permanece; verifique sempre os números após a importação.

Tenho de instalar um plugin de popup separado? Posso usar apenas um alert?

Tecnicamente sim: substitua SPU.show(N) por alert('Thank you!') e uma notificação aparecerá. Mas o alert bloqueia a página, parece deslocado e incomoda os visitantes. Uma popup personalizada com o seu design, ícone e animação suave faz parte do site, em vez de ser um diálogo do sistema do navegador. Na nossa experiência em vários projetos, substituir o alert por uma popup com a sua marca reduz visivelmente a taxa de rejeição imediata.

O código só funciona para um formulário. Como faço para funcionar com vários formulários?

Use a filtragem por event.detail.contactFormId. Para a variante jQuery, envolva a chamada numa verificação: if (event.detail.contactFormId === 123) { SPU.show(1068); }. Para JavaScript vanilla, um exemplo com uma condição é fornecido no passo 3.

E se o jQuery não estiver carregado no site?

Use a variante addEventListener do passo 3. Não requer jQuery e funciona em todos os navegadores modernos. A única nuance: fechar a popup via DOM nativo é feito ocultando manualmente o elemento, uma vez que o método fadeOut não está disponível. Como alternativa, adicione uma classe CSS com transition e alterne-a.

Posso usar uma popup para todos os formulários do site?

Sim, se o texto da notificação for universal. Crie uma popup de sucesso e uma de erro e, em seguida, abra-as para todos os eventos wpcf7mailsent e wpcf7invalid sem filtrar por contactFormId. No entanto, se os formulários em páginas diferentes tiverem contextos diferentes, é melhor criar janelas separadas. «Pedido de consulta recebido» e «Subscrição confirmada» têm aspetos diferentes.

Popup Maker ou WP Popups: qual escolher para o seu projeto

A escolha resume-se a três cenários:

• Precisa do máximo de funcionalidades e integrações? Opte pelo Popup Maker. Segmentação por página, acionadores de tempo e scroll, integração com dezenas de plugins de formulários, uma comunidade enorme. O núcleo gratuito cobre 90% dos casos de uso.
• Quer simplicidade e um editor visual Gutenberg? A sua escolha é o WP Popups. Interface moderna, configuração rápida, menos sobrecarga. Funciona com o Contact Form 7 de raiz.
• Precisa de uma popup com um formulário do Contact Form 7 lá dentro? Esse é um cenário diferente (não notificações após o envio, mas um formulário numa janela modal acionada por um clique num botão). Para isso, existe o plugin especializado WPB Popup for Contact Form 7, que abre um formulário CF7 numa popup, em vez de reagir ao seu envio.

Ambos os plugins de notificação são gratuitos e estão disponíveis no diretório WordPress.org. Escolha o que melhor se adapta ao seu stack e substitua a chamada da sua API no script do passo 3. O tópico das popups pode ser explorado infinitamente: testes A/B do texto da notificação, atrasos baseados no tempo de leitura, janelas diferentes para formulários diferentes. Mas a base (evento CF7 + chamada da popup + fecho automático) cobre a grande maioria das tarefas reais em sites WordPress.