Contact Form 7 Integration

Geo Controller integrates with Contact Form 7, allowing you to automatically include visitor geolocation information in contact form submissions and email notifications.

The integration adds dedicated geographic form tags to Contact Form 7. These tags generate hidden form fields containing information detected by Geo Controller, such as the visitor’s country, city, region, or IP address.

This functionality is useful for international contact forms, customer support requests, geographic lead analysis, and applications that need basic location context alongside submitted information.

How the Integration Works

Geo Controller registers additional Contact Form 7 form tags based on available geographic properties returned by its API.

Each registered tag generates a hidden HTML input containing the corresponding geographic value. Visitors do not see these inputs in the form, but their values can be submitted together with the other form fields.

For example, the following form tag:

[country visitor_country]

Generates a hidden input named visitor_country. Its value is populated with the country detected by Geo Controller when the form is rendered.

If the visitor is detected in the United States, the generated HTML may resemble:

<input type="hidden" name="visitor_country" value="United States">

The actual generated input also contains additional attributes used by Geo Controller and Contact Form 7.

You can then include the submitted value in your email notification using the corresponding Contact Form 7 mail tag:

[visitor_country]

Important: Geo Controller geographic form tags are Contact Form 7 form tags. Their syntax and email integration follow the standard Contact Form 7 field and mail-tag conventions.

Enable Contact Form 7 Integration

Before using geographic fields, ensure that both Geo Controller and Contact Form 7 are installed and activated.

Open your WordPress administration dashboard.
Navigate to the Geo Controller plugin settings.
Locate the Contact Form 7 integration option.
Enable the integration.
Save the settings using the available update button.

Depending on your Geo Controller version, the settings interface may use older labels such as Geo Plugin and Update all Options.

Once enabled, open an existing Contact Form 7 form or create a new one.

Geo Controller registers additional geographic field generators in the Contact Form 7 editor. The available fields depend on the geographic properties supported by the installed Geo Controller version.

Understanding Geographic Form Tags

A Geo Controller field uses the following format:

[geographic_property field_name]

The first parameter identifies the Geo Controller geographic property. The second parameter defines the Contact Form 7 field name.

For example:

[country visitor_country]

In this example:

country identifies the geographic property returned by Geo Controller.
visitor_country is the name of the hidden Contact Form 7 field.
[visitor_country] is the corresponding mail tag used in email notifications.

You can choose your own field names, provided they follow Contact Form 7 naming conventions and do not conflict with other fields in the form.

Available Geographic Fields

Geo Controller automatically registers supported geographic properties returned by its API, excluding internal, unsupported, or intentionally restricted properties.

Depending on your installed version and available geolocation data, you may be able to use fields such as:

Form Tag	Purpose
`[country visitor_country]`	Visitor’s detected country.
`[countryCode visitor_country_code]`	Country code, if the property is available.
`[city visitor_city]`	Visitor’s detected city.
`[region visitor_region]`	Visitor’s detected region.
`[continent visitor_continent]`	Visitor’s detected continent.
`[ip visitor_ip]`	IP address returned by Geo Controller.

Note: Geographic property names are case-sensitive. The exact available fields depend on the Geo Controller API response and the integration’s exclusion list. Use the field generator in your installation to confirm supported names.

For more information about geographic properties, see the Geo Controller Tags documentation.

Example: Add Visitor Location to a Contact Form

Suppose you have a contact form containing the visitor’s name, email address, subject, and message.

You can extend it with hidden geographic fields to include detected location information without asking the visitor to enter it manually.

Step 1: Edit the Contact Form

Open your form in Contact Form 7 and switch to the Form tab.

For example, you can use the following form template:

<label>Your Name
[text* your-name]
</label>

<label>Your Email
[email* your-email]
</label>

<label>Subject
[text your-subject]
</label>

<label>Your Message
[textarea your-message]
</label>

[country visitor_country]
[city visitor_city]
[region visitor_region]

[submit "Send Message"]

The geographic tags create hidden fields that do not appear as visible form controls.

When the page is generated, Geo Controller populates them with the corresponding detected values.

Step 2: Add Geographic Information to the Email

Switch to the Mail tab in Contact Form 7.

Add the corresponding mail tags to your message body:

Name: [your-name]
Email: [your-email]
Subject: [your-subject]

Message:
[your-message]

Visitor Location:
Country: [visitor_country]
City: [visitor_city]
Region: [visitor_region]

Each mail tag must match the field name defined in the form template.

For example, a form field named visitor_country is referenced using [visitor_country], not [country].

Step 3: Test the Form

Save the form and open the page where it is displayed.

Submit a test message and check the received email.

Depending on the detected location, the email might contain:

Visitor Location:
Country: United States
City: New York
Region: New York

These values are illustrative. Actual results depend on the visitor’s IP address and the accuracy and availability of the underlying geolocation data.

Example: Collect the Visitor’s IP Address

If your application requires an IP address as part of the submitted information, Geo Controller provides an IP-related geographic form tag when that property is available.

Add the following to your Contact Form 7 form:

[ip visitor_ip]

Then include the corresponding mail tag in your email template:

Visitor IP: [visitor_ip]

The field receives the IP address provided by Geo Controller during form rendering.

Privacy notice: IP addresses may constitute personal data. Collect and retain them only where necessary, with an appropriate lawful basis and suitable privacy information.

How Hidden Geographic Fields Behave

Geo Controller’s Contact Form 7 integration generates HTML inputs using type="hidden".

These fields are populated when the form is generated and submitted with the other form data.

Because the values are part of the HTML form, they can be inspected or modified using browser developer tools or other client-side methods.

Important: Hidden geographic fields are not a trusted security mechanism. Do not rely on submitted geographic field values alone for access control, fraud detection, tax calculation, payment restrictions, or other sensitive decisions.

For security-sensitive operations, perform independent server-side validation using trusted request information and appropriate application logic.

Using Geographic Fields with Page Caching

Geo Controller populates geographic form fields during server-side form rendering.

If a full-page cache, reverse proxy, or CDN stores the generated HTML, visitors may receive geographic values originally generated for another request.

For example, a contact form cached with the country value United States may continue sending that value for visitors from other countries.

This can happen when page caching does not distinguish requests by geographic location.

To reduce the risk of incorrect geographic information:

Review the page caching configuration for pages containing geographic fields.
Ensure location-dependent HTML is generated separately when required.
Test forms from different geographic locations.
Verify the actual hidden input values before submitting a test form.

The Contact Form 7 integration does not independently guarantee location-aware full-page caching.

Privacy and Data Protection

Geographic data should be collected only when it serves a legitimate purpose.

Country-level information may be sufficient for geographic lead analysis or customer service routing. More precise information, including IP addresses, may require additional privacy considerations.

Before collecting geographic data through contact forms:

Determine which geographic properties are actually necessary.
Explain relevant data collection in your privacy notice.
Apply an appropriate legal basis where data protection law requires one.
Avoid storing or distributing unnecessary personal information.
Review the retention and access policies associated with your contact form submissions.

Using hidden form fields does not remove applicable privacy obligations.

Customizing Available Geographic Fields

Geo Controller includes a WordPress filter that allows developers to modify the list of geographic properties excluded from Contact Form 7 registration.

The filter is:

cfgeo_wpcf7_excluded

For example, a developer can exclude the IP field from the Contact Form 7 integration:

add_filter('cfgeo_wpcf7_excluded', function ($excluded) {
    $excluded[] = 'ip';
    return array_unique($excluded);
});

This example adds the ip property to the exclusion list without removing the default exclusions.

Excluded properties are not registered as Geo Controller form tags or added to the integration’s field generator.

Developer note: Geo Controller excludes a number of internal API fields by default, including selected network flags, error information, license-related fields, and other implementation-specific properties. Changing this list should be done carefully.

Troubleshooting

Geo Controller Fields Do Not Appear

If geographic field generators are missing from the Contact Form 7 editor:

Verify that both plugins are activated.
Confirm that the Contact Form 7 integration is enabled in Geo Controller settings.
Check whether Geo Controller can retrieve geographic information.
Confirm that the requested field is not excluded from the integration.
Review WordPress PHP error logs for integration-related errors.

Geographic Values Are Empty

If a field is generated but contains no geographic value:

Verify that the geographic property is supported and contains data.
Check the property name and its capitalization.
Inspect the hidden input in the generated HTML.
Check whether another plugin changes the form markup.
Test without full-page caching.

The Email Does Not Contain Geographic Information

Make sure the email mail tag matches the field name in the form template.

For example:

Form tag: [country visitor_country]
Mail tag: [visitor_country]

Check that the mail template contains the correct field name and that the field exists in the submitted form.

Incorrect Geographic Information

Geo Controller uses IP-based geolocation information, which is not guaranteed to represent the visitor’s precise physical location.

VPN connections, proxies, corporate networks, mobile networks, and inaccurate IP geolocation records may affect the returned values.

Page caching can also cause incorrect values if previously generated location-dependent HTML is reused.

For Developers

The Contact Form 7 integration is implemented through the CFGP__Plugin__contact_form_7 class.

Its primary integration points include:

wpcf7_init — registers supported geographic form tags using wpcf7_add_form_tag().
wpcf7_admin_init — registers geographic field generators in the Contact Form 7 administration interface.
wpcf7_form_elements — applies WordPress shortcode processing to the generated form markup.
cfgeo_wpcf7_excluded — allows developers to customize the excluded geographic property list.

Each generated field retrieves its value through the Geo Controller API and renders a hidden input with the corresponding form field name.

The implementation also supports supplied form-tag values and processes supported form-tag options when constructing input attributes.

Developers should validate any geographic values received from the submitted form before using them in sensitive operations.

Important: Geo Controller’s Contact Form 7 integration simplifies the collection of geographic context in contact forms. Geographic values depend on IP-based geolocation accuracy, form rendering, and caching configuration. Hidden field values can be modified by visitors and must not be treated as verified security information.