WordPress Contact Form 7 Hook Unofficial Developer Documentation and Examples

by
on September 21, 2012

There is a lot of confusion around the Internet on how to properly configure action hooks in Contact Form 7. A few days ago I spent a few hours developing a plugin to customize and enable some intelligent detection of the forms data and I got it to work. From what I’ve seen around the Internet, there is no official documentation and most of the forum questions and threads are not answered so in this developers’ tutorial I’ll try to answer all these questions here.

IMPORTANT: Please note that some things have changed in the latest version (3.9) of the plugin, I will update this post ASAP, see Andrew’s comment for the changes. Documentation below is valid for v3.8 and below.

This post is not dedicated to solve errors like “Emails not getting sent”, “How to increase textbox size” and so on, that’s a server missconfiguration or some CSS code, here we’ll just go through the Contact Form 7 action hook┬áprovided and how to code your own WordPress plugin to improve WPCF7. I’ll start with the basics so everyone can follow this and then move to more complex features:

Creating a WordPress plugin

You need to know PHP code and have access to the files in your server. Then, create a .php file and copy-paste this:

/*
Plugin Name: Contact Form 7 special functionalities
Plugin URI: http://xaviesteve.com/
Description: 
Author: Xavi Esteve
Version: 0.1b
Author URI: http://xaviesteve.com/
*/
function wpcf7_do_something (&$WPCF7_ContactForm) {
    // Our code will go here
}
add_action("wpcf7_before_send_mail", "wpcf7_do_something");

Change the plugin name and author and we now have a simple plugin that creates an action hook into CF7. Upload this file to your /wp-content/plugins/ folder and enable it in the WordPress Dashboard.

Note: the & symbol in the function parameter references the object so that any change done inside the hook will also be reflected later in CF7.

Understanding the CF7 object

One of the main issues with users having problems with Contact Form 7s’ hook is that they don’t understand how the object works, here’s a full example of the object for your reference. If you look at it closely you’ll see how it starts being a PHP object but then those objects are arrays so you always need to call the CF7 object like object->object['array']. Also, returning the object at the end of the function is not required but a good practice.

WPCF7_ContactForm Object
(
    [initial] => 
    [id] => 577
    [title] => Home page form
    [unit_tag] => 
    [responses_count] => 0
    [scanned_form_tags] => Array
        (
            [0] => Array
                (
                    [type] => text*
                    [name] => name
                    [options] => Array
                        (
                            [0] => id:firstfield
                        )

                    [raw_values] => Array
                        (
                        )

                    [values] => Array
                        (
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                )

                        )

                    [labels] => Array
                        (
                        )

                    [attr] => 
                    [content] => 
                )

            [1] => Array
                (
                    [type] => email
                    [name] => email
                    [options] => Array
                        (
                        )

                    [raw_values] => Array
                        (
                        )

                    [values] => Array
                        (
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                )

                        )

                    [labels] => Array
                        (
                        )

                    [attr] => 
                    [content] => 
                )

            [2] => Array
                (
                    [type] => text*
                    [name] => phone
                    [options] => Array
                        (
                        )

                    [raw_values] => Array
                        (
                        )

                    [values] => Array
                        (
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                )

                        )

                    [labels] => Array
                        (
                        )

                    [attr] => 
                    [content] => 
                )

            [3] => Array
                (
                    [type] => textarea
                    [name] => message
                    [options] => Array
                        (
                        )

                    [raw_values] => Array
                        (
                        )

                    [values] => Array
                        (
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                )

                        )

                    [labels] => Array
                        (
                        )

                    [attr] => 
                    [content] => 
                )

            [4] => Array
                (
                    [type] => submit
                    [name] => 
                    [options] => Array
                        (
                            [0] => class:button
                        )

                    [raw_values] => Array
                        (
                            [0] => Send
                        )

                    [values] => Array
                        (
                            [0] => Send
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                    [0] => WPCF7_Pipe Object
                                        (
                                            [before] => Send
                                            [after] => Send
                                        )

                                )

                        )

                    [labels] => Array
                        (
                            [0] => Send
                        )

                    [attr] => 
                    [content] => 
                )

        )

    [posted_data] => Array
        (
            [_wpcf7] => 577
            [_wpcf7_version] => 3.2.1
            [_wpcf7_unit_tag] => wpcf7-f577-p2-o1
            [_wpnonce] => 8dabc14d71
            [name] => John Moore
            [email] => johnmoore@gmail.com
            [phone] => 07912345678
            [message] => I am interested to know more about your company
            [_wpcf7_is_ajax_call] => 1
        )

    [uploaded_files] => Array
        (
        )

    [skip_mail] => 
    [form] => 
Name

    [text* name] 

Email

    [email email] 

Phone

    [text* phone] 

Enquiry

    [textarea message] 

[submit class:button "Send"]

    [mail] => Array
        (
            [subject] => MyWebsite - New form submission
            [sender] => MyWebsite <noreply@xaviesteve.com> 
            [body] => 
            [recipient] => Xavi <xavi@gmail.com> 
            [additional_headers] => 
            [attachments] => 
            [use_html] => 1
        )

    [mail_2] => Array
        (
            [active] => 
            [subject] => 
            [sender] => 
            [body] => 
            [recipient] => 
            [additional_headers] => 
            [attachments] => 
            [use_html] => 
        )

    [messages] => Array
        (
            [mail_sent_ok] => Your message was sent successfully. We will call you soon.
            [mail_sent_ng] => Failed to send your message. Please try later or contact administrator by other way.
            [akismet_says_spam] => Failed to send your message. Please try later or contact administrator by other way.
            [validation_error] => Please fill in the required fields and submit the form again.
            [accept_terms] => Please accept the terms to proceed.
            [invalid_email] => Email address seems invalid.
            [invalid_required] => Please fill the required field.
            [captcha_not_match] => Your entered code is incorrect.
            [upload_failed] => Failed to upload file.
            [upload_file_type_invalid] => This file type is not allowed.
            [upload_file_too_large] => This file is too large.
            [upload_failed_php_error] => Failed to upload file. Error occurred.
            [quiz_answer_not_correct] => Your answer is not correct.
        )

    [additional_settings] => 
    [submit_time] => 1348136521.36
    [ip] => 82.18.147.15
)

 

Contact Form 7 action hook examples

So that’s pretty much it, creating a WordPress action hook to the wpcf7_before_send_mail and understanding how to traverse the object should allow any midweight PHP developer to do pretty much anything with it. Let’s see some examples, to use them get the piece of code at the top of the article and put it inside.

Reading a posted value in the form with PHP

$firstname = $WPCF7_ContactForm->posted_data['firstname'];

Having multiple email recipients

No need to code any PHP for this, just go to edit the form through the WordPress Dashboard and add different emails separated by commas:

John <john@gmail.com>,Mark <mark@gmail.com>

Changing email recipient dynamically depending on code

if ($WPCF7_ContactForm->posted_data['radiobuttonname'] == "Yes") {
    $WPCF7_ContactForm->mail['recipient'] = "John <john@gmail.com>";
}else{
    $WPCF7_ContactForm->mail['recipient'] = "Mark <mark@gmail.com>";
}

Avoiding CF7 from sending email

Change the skip_mail value to true.

$wpcf7_data->skip_mail = true;

Redirecting someone to a different page depending on submitted data

The additional_settings is what we need to change. Here’s a self explanatory example:

if ($foo == "provider") {
    $wpcf7_data->additional_settings = "on_sent_ok: \"location.replace('http://xaviesteve.com//provider/');\"";
}else{
    $wpcf7_data->additional_settings = "on_sent_ok: \"location.replace('http://xaviesteve.com//client/');\"";
}

Note: My WordPress removed some code when publishing it, remember to add backward slashes to the inner double quotes in the code above.

Adding more text in the sent email

For example, we can add the users’ IP address:

$wpcf7_data->mail['body'] .= '<p>IP Address: '.$_SERVER['REMOTE_ADDR'].'</p>';

Get page from which form was submitted

$pagesubmitted = $_SERVER['HTTP_REFERER'];

That’s it!

You should now have total control over the Contact Form 7 plugin. For any other examples or questions on the code please feel free to comment below, for other issues please visit the Contact Form 7 official WordPress forum.

Note There are 13 invites left to get 20GB of free storage space on Copy.com, great to share your summer trip's photos with your friends.

Thank you for sharing the article

    
    

Xavi Esteve wrote this article on September 21, 2012 and published it in web design, php, wordpress, tutorials, english and work.

30 comments

  • ivandurham says:

    Awesome post dude. You are going really well in blogging. I like it really much. Keep up the good work !

  • Seth Etter says:

    Thanks for this, very helpful.

  • Jonas says:

    Thanks, just what I was looking for.
    Just one question, is it possible to output:

    $wpcf7_data->mail['body']

    but then replace the variables with the posted ones?
    in other words, is it possible to get the mail body of the mail 1 or 2 being send?

  • Andrea Moro says:

    Hello there,

    thanks for the interesting post. It gave me a lot of indication and I was wondering if you can perhaps help me to encapsulate the name of the sender in a session variable I can recall in the subsequent Thank you page.

    What I did in my function.php code is

    function get_contact_form_details($cf7){
    $_SESSION['cf7data'] = $cf7->posted_data;
    return false;
    }
    add_action( ‘wpcf7_before_send_mail’, ‘get_contact_form_details’ );

    whereas in the thank you page I have this code

    Hi,

    but nothing appear on screen, like the value has never been stored. Any help?

    Thanks

  • Xavi Author says:

    Hi Andrea,

    I would suggest you to post your question here: http://wordpress.org/support/plugin/contact-form-7

    The author of the plugin itself and thousands of developers will be able to help you faster than myself (I’m quite busy these days).

    Cheers

  • Cube3x says:

    Your post really helped me to add contact form 7 name and email to my email marketing site. Thanks for writing this post.

  • tonyb says:

    Thanks for this useful information.

    I used your plugin but had problems getting all your snippets of code to work.

    Then I realised the ones that use:

    $WPCF7_ContactForm-> worked, and those that use

    $wpcf7_data-> didn’t work.

    When I substituted the former for the latter, the other snippets worked as well. Wonderful!

    Tony

  • Sanket Vyas says:

    I Use Contact form 7

    add_action('wpcf7_before_send_mail','save_to_the_database');
    function save_to_the_database($cf7) {
    	global $wpdb;
    	//declare your varialbes, for example:
    	$id = $cf7->posted_data["id"];
    	$first_name = $cf7->posted_data["first-name"];
    	$email_txt = $cf7->posted_data["email-id"];
    	
    	//echo $ticket_id;
    	$result = $wpdb->get_results( "INSERT INTO databasename (`id`, `firstname`, `emailid`) VALUES ('$id','$first_name','$email_txt')");
    }

    Its work fine , also insert data into database.

    Now I have Three Contact Form, contact-form-7 id="411" contact-form-7 id="412" and contact-form-7 id="413"

    How can I trigger

    If id of form = 411, Insert into DB -> Table1
    If id of form = 412, Insert into DB -> Table2
    If id of form = 413, Insert into DB -> Table3
  • Javayim says:

    Just perfect, thanks !

  • MikeS says:

    Sorry but I’m new to to programming.
    Where exactly will I add this codes?

  • MarcelM says:

    Thanks Xavi this was a huge help. I spent a while searching and this is exactly what I needed.

  • Krony says:

    Thank you, exactly that’s what i’ve been searching for :)

  • Y-Love says:

    Thank you SO much for this, I’ve been searching everywhere for this. Fantastic post.

  • Patrick Van Hoof says:

    Hello Xavier

    My contact form title is ‘guide_pvh’

    The code is :
    title;
    //if ($title==’pvh_guide’){
    // $wpcf7_data->additional_settings = “on_sent_ok: \”location.replace(‘http://locationcontainernamur.com/blog/’);\””;
    //}else{
    // $wpcf7_data->additional_settings = “on_sent_ok: \”location.replace(‘http://google.com’);\””;
    //}
    $wpcf7_data->additional_settings = “on_sent_ok: \”location.replace(‘http://locationcontainernamur.com/blog/’);\””;
    }
    add_action(“wpcf7_before_send_mail”, “wpcf7_do_something”);
    ?>

    but although CF7 told me that the message was sent, in my code the redirection does not work, you have an idea of the problem?

  • Etienne says:

    Hi Xavi, thanks a lot for this excellent post. As one of the (lower end) midweight PHP developer, this is what I needed.

  • barry says:

    Hello Xavi,

    I like to pick your brain: do you know if a CF7 form can have multiple thank-you redirections based on selected form values??

    i am testing with a custom function in functions.php but i dont see an appropiate hook.

    Any ideas, tips?

  • Xavi Author says:

    Hello barry,

    Yes, copy the code at “Redirecting someone to a different page depending on submitted data” but instead of $foo == "provider" use $_GET['the-select-field-name'] == "option1", etc.

    You may want put that in a plugin instead of the functions.php, the code at “Creating a WordPress plugin” in the article should work for you.

    Cheers,
    Xavi

  • Laura says:

    Thank You! I have two CF7 forms and Flamingo installed. Would this be a way I can prevent one of the forms from being saved in the database from the Flamingo plugin?

  • Xavi Author says:

    Hi Laura, I can’t tell for sure but it should. Try returning an empty variable for $WPCF7_ContactForm.

  • Sohail says:

    Hi Xavi,

    Would this not work if write this in functions.php file ?

  • Xavi Author says:

    Hi Sohail,
    It will, just make sure to call it through the hook (add_action…).

  • Pratik says:

    “WordPress Contact 7 , make Conditional Email Body ??”

    Hello i am using Contact 7 form plugin. I get option to have HTML body for email template like

    Name:

    [your-name]

    Here [your-name] is actually value of textbox,I Dont want to make REQUIRED field,

    So what i want is IF THE NAME TEXT BOX VALUE is filled only then show labels and textbox value.Means show the above given Table in email ONLY IF IT IS FILLED .

    I searched a lot ,i didnt get any help on any website ,Please help me .Thanks

  • Xavi Author says:

    Hi Pratik,

    The email is in this variable: $wpcf7_data->mail['body'] so you can modify it freely. You can even empty it and start filling it conditionally:

    $wpcf7_data->mail['body'] = "";
    if ($wpcf7_data->posted_data['your-name']) {
        $wpcf7_data->mail['body'] .= "Hello [your-name]!";
    }

    untested code

  • remco says:

    Hi Xavi,

    I like to redirect when email is not successfully send. Have you got an idea for this? Thanks, Remco

  • mary says:

    Hi Xavi,
    I’m new to wordpress so I’m having some issues.
    I need to change the recipient mail address based on a parameter that is called $citta (it means city)and is in the url of the page where the form is (ex. http://www.test.com?citta=Florence). So, if $citta is equal to Rome the form must send to a certain address and so on.
    I created a plugin following your tutorial but when I compile the form it does not send anything.
    Could you possibly check my code? Thank you so much.
    A last question: what should I write in the recipient (To) field in Contact form editing page? I wrote [recipient] but I am not sure about it.

    function wpcf7_do_something (&$WPCF7_ContactForm) {
    if ($citta == “Rome”) {
    $WPCF7_ContactForm->mail['recipient'] = “Rome “;
    }
    if ($citta == “Turin”) {
    $WPCF7_ContactForm->mail['recipient'] = “Turin “;
    }
    if ($citta == “Florence”) {
    $WPCF7_ContactForm->mail['recipient'] = “Florence “;
    }
    }
    add_action(“wpcf7_before_send_mail”, “wpcf7_do_something”);

  • Rob W says:

    FYI, this code will need to be updated to reflect the latest version of WPCF7 (3.9)… The access to the posted data has changed. See: http://contactform7.com/2014/07/02/contact-form-7-39-beta/

    This was code example was causing headaches when posted_data was NULL… see link on how to access data.

  • Vir J says:

    Hey thanks Xavi for this wonderful article..

    Though it did not solved my problem but I was able to manage to catch the tweak required for adding this data to salesforce CRM and was successful.

    I had to replace $wpcf7_data->posted_data['your-name'] with $POST['your-name'] to get the data of form fields.. else it was all coming blank variables.

    Anyways, Thanks for the post.

    Good Luck.

  • Andrew says:

    Wanted to say thanks. With the new release at http://contactform7.com/2014/07/02/contact-form-7-39-beta/ I wanted to mention that some of these have changed. Until I found that reference it was a little bit of a pain to debug!

    For example a new URL redirect is

    $goURL = 'http://contactform7.com';
    $cfdata->set_properties( array( 'additional_settings' => "on_sent_ok: \"location = '".$goURL."';\"" ) );
  • Xavi Author says:

    Thanks a lot Vir J and Andrew, I’ll update the post ASAP.

  • Classic Mike says:

    Hi Thanks for the post. Just a heads up apparently the original developer has changed the way how you can get and modify the posted data in contact form 3.9. If you would like you can look the link here: http://contactform7.com/2014/07/02/contact-form-7-39-beta/