Como usar o Gravity Forms: formulários, lógica condicional e e-mails

Este artigo é uma edição localizada do original em japonês. Ler o original em japonês

O Gravity Forms é um plugin de formulários pago, que não é distribuído pelo WordPress.org. Pelo painel de administração, dá para configurar a "lógica condicional" (que mostra ou esconde campos conforme as respostas), o direcionamento das notificações conforme o conteúdo enviado, o armazenamento no banco de dados e a exportação dos dados enviados (entries). Este artigo explica como criar um formulário básico e como usar os hooks para desenvolvedores. O conteúdo das licenças e os nomes dos itens das telas foram conferidos, em novembro de 2026, no site oficial e na documentação (em inglês) do Gravity Forms. As telas são descritas com os nomes dos itens em inglês; se a sua estiver em português, os nomes podem ser diferentes.

Licenças e add-ons disponíveis

O número de sites e os add-ons disponíveis variam conforme a licença.

O add-on Webhooks, que envia os dados recebidos para sistemas externos, só está disponível no Elite (e na licença para organizações sem fins lucrativos). Stripe e PayPal Checkout, para pagamentos, estão a partir do Pro. Antes de comprar, confira na página oficial de preços em qual licença está incluído o add-on de que você precisa.

Instalação e registro da chave de licença

Baixe o arquivo ZIP do plugin na página da conta no site oficial do Gravity Forms, instale-o em "Plugins → Adicionar novo plugin → Enviar plugin" (Plugins → Add New → Upload Plugin) e ative-o. Com o WP-CLI, é assim.

wp plugin install /path/to/gravityforms.zip --activate

A chave de licença é informada na tela "Forms → Settings". Se você distribui a mesma configuração para vários ambientes, também dá para escrevê-la como constante no wp-config.php. Quando a constante está definida, o campo da chave de licença na tela de configurações passa a ser exibido como não editável.

define( 'GF_LICENSE_KEY', 'YOUR-LICENSE-KEY-HERE' );

Crie o formulário e coloque-o no site

1. No painel, abra "Forms → New Form", dê um nome ao formulário e crie-o.
2. Em "Add Fields", à direita, posicione campos como nome (Name), e-mail (Email), telefone (Phone), lista de opções (Drop Down), texto longo (Paragraph Text) e caixa de consentimento (Consent).
3. Ao clicar em cada campo, as configurações dele se abrem. Nos campos obrigatórios, ative "Required".
4. Salve com "Save Form".

Para colocar o formulário em uma página, adicione o bloco "Gravity Forms" no editor de blocos e escolha o formulário criado. Para usar o shortcode, siga o formato abaixo, em que id é o ID do formulário exibido na lista de formulários.

[gravityform id="1" title="false"]

Mostre ou esconda campos com a lógica condicional

Para fazer algo como "só mostrar o campo de envio do currículo quando o tipo de contato for 'Vagas de emprego'", use a lógica condicional (Conditional Logic).

1. No editor do formulário, clique no campo que você quer mostrar ou esconder (por exemplo, o upload de arquivo do currículo).
2. Nas configurações do campo, abra "Conditional Logic" e ative "Enable Conditional Logic".
3. Escolha "Show" (mostrar) ou "Hide" (esconder) e, para as condições, "All" (todas satisfeitas) ou "Any" (qualquer uma satisfeita).
4. Na linha da condição, escolha o campo de origem (tipo de contato), a comparação (is) e o valor (Vagas de emprego). O sinal de mais ao lado da linha permite adicionar condições.

Também é possível definir lógica condicional separadamente para os e-mails de notificação e para as mensagens de confirmação.

Configure os e-mails de notificação

Os e-mails de notificação são configurados em "Forms → formulário desejado → Form Settings → Notifications". Quando você cria um formulário, já existe uma notificação para o administrador. Com "Add New", adicione notificações como a resposta automática.

As merge tags são marcadores que inserem os valores enviados. O valor de um campo tem o formato {Rótulo:IDdoCampo} (por exemplo, {Name:1}; também funciona omitir o rótulo, como em {:1}), e {all_fields} insere todo o conteúdo preenchido em uma tabela. Se você escolher pelo botão de merge tag no canto superior direito do campo de mensagem, consegue preencher sem precisar descobrir o ID do campo.

Se o endereço do remetente for do mesmo domínio do site, a mensagem tende menos a ser tratada como spam. Evite usar como remetente o e-mail de quem entrou em contato; coloque-o no Reply To.

Mensagem de confirmação após o envio

O que é exibido após o envio é configurado em "Form Settings → Confirmations". Há três tipos.

• Text: exibe uma mensagem no lugar do formulário (padrão)
• Page: leva a uma página dentro do site
• Redirect: leva a uma URL especificada

Se você prepara uma página de conclusão do envio para usar em medições de anúncios ou análise de acessos, escolha Page ou Redirect.

Adicione validações com PHP

As validações que as configurações do painel não cobrem podem ser adicionadas com o filtro gform_field_validation. Se você acrescentar _IDdoFormulário_IDdoCampo depois do nome do hook, ele se aplica só a esse campo. O exemplo a seguir valida o telefone digitado no campo de ID 3 do formulário de ID 1 (o formato de telefone usado aqui é o do Japão). Escreva no functions.php do tema ou em um plugin próprio.

<?php
// Valida o telefone do formulário de ID 1, campo de ID 3
add_filter( 'gform_field_validation_1_3', function ( $result, $value, $form, $field ) {
	if ( ! is_string( $value ) || '' === $value ) {
		return $result; // O tratamento de campo vazio fica por conta da configuração "Required" do campo
	}

	$digits = str_replace( array( '-', ' ' ), '', $value );

	if ( ! preg_match( '/^0\d{9,10}$/', $digits ) ) {
		$result['is_valid'] = false;
		$result['message']  = 'O telefone deve começar com 0 e ter 10 ou 11 dígitos (hífens são permitidos).';
	}

	return $result;
}, 10, 4 );

O ID do formulário e o ID do campo aparecem quando você seleciona o campo no editor do formulário. Se você refizer o formulário, os IDs mudam; por isso, confirme que os IDs são iguais na produção e no ambiente de desenvolvimento.

Notifique sistemas externos após o envio

Em uma licença que não tem o add-on Webhooks, se você quiser avisar o Slack ou outro serviço a cada envio, pode escrever o processamento com a action gform_after_submission. Essa action é executada depois que a entry é salva e os e-mails de notificação são enviados. Ela também é executada para entries classificadas como spam, então verifique o status antes de enviar. Em licenças Pro ou superiores, também dá para configurar pelo add-on do Slack ou pelo add-on do Zapier.

<?php
// Após o envio do formulário de ID 1, avisa o Incoming Webhook do Slack
add_action( 'gform_after_submission_1', function ( $entry, $form ) {
	if ( 'spam' === rgar( $entry, 'status' ) ) {
		return;
	}

	// Escreva a URL do Webhook no wp-config.php com define( 'MY_SLACK_WEBHOOK_URL', '...' );
	if ( ! defined( 'MY_SLACK_WEBHOOK_URL' ) ) {
		return;
	}

	wp_remote_post( MY_SLACK_WEBHOOK_URL, array(
		'headers' => array( 'Content-Type' => 'application/json' ),
		'body'    => wp_json_encode( array(
			'text' => sprintf( 'Novo contato: %s', rgar( $entry, '1' ) ),
		) ),
		'timeout' => 5,
	) );
}, 10, 2 );

O rgar( $entry, '1' ) é o valor do campo de ID 1. Em campos com vários campos de preenchimento, como o campo de nome (Name), os valores são obtidos com IDs com ponto decimal, como '1.3' (nome) e '1.6' (sobrenome). A URL do Webhook é uma informação secreta, então não a escreva diretamente no código nem a inclua em repositórios públicos.

Confira e exporte as entries

Os dados enviados são salvos no banco de dados do WordPress e podem ser listados em "Forms → Entries". Para exportar em CSV, abra "Forms → Import/Export", escolha o formulário em "Export Entries", indique os campos e o período a exportar e baixe o arquivo.

Para obtê-las pelo PHP, use GFAPI::get_entries(). Este é um exemplo para ver as 10 mais recentes com o WP-CLI.

wp eval 'echo wp_json_encode( GFAPI::get_entries( 1, array(), null, array( "offset" => 0, "page_size" => 10 ) ) );'

Pontos de atenção

• Os dados enviados contêm informações pessoais. Se não for preciso guardá-los, defina como tratá-los: por exemplo, estabeleça nas configurações do formulário um prazo de armazenamento e a exclusão, e não deixe CSVs exportados esquecidos.
• Quando os e-mails de notificação não chegam, muitas vezes a causa não é o Gravity Forms, e sim o envio de e-mails do servidor. Usar um plugin que envie por SMTP às vezes melhora a situação.
• Antes de adicionar código PHP, confirme em um ambiente de homologação se o ID do formulário e o ID do campo estão corretos e se funciona.

Dúvidas sobre WordPress? Quem publica este site fica no Japão e responde em japonês. Contato (em japonês)