What are tokens and why do I need them?
Tokens allow you to add personal touches to actions and emails within Campaignion. They might be as simple as adding the supporter's name to the salutation line in a thank you email, e.g.
"Hi John, thanks for signing the petition".
But they can also allow you to do more complex things like customise the email sent to MPs with both details about the MP and the supporter, e.g.
"Dear Mr Corbyn MP,
As my Labour MP, I know you must care about X. This issue matters to me because I ride my bike to work every day..."
The tokens themselves are simple pieces of code that act as place-holders for this supporter/target information. Tokens are transformed into the related piece of information before the user sees them, so your supporters will never see them in their ugly code form.
How do they work?
Tokens take a piece of information from the Campaignion system and allow you to display it in a supporter email, counter bar or an email to target. In order for you to be able to add a piece of information using a token, it has to already be stored either in Campaignion itself (for target data) or in the user's session.
This means that when you want to use supporter data, you must have first stored that data in the session. Simply put, this means that the user has to enter this information and click on a submit button. So you can only display information using tokens from the second page of your action onwards. They won't work on landing pages.
Finding the right token
The format of the token you need depends on where you're using it. Token formats that work in emails won't work on landing pages for example. We know, it's a little confusing. So we've put together this guide on what tokens you can and should use where.
As always, if you have any questions, feel free to get in touch!
Counter / Progress Bar Tokens
!current ---> shows the current number of supporters
!current-animated ---> shows the current number of supporters but has animated counting from 0 upwards
!target ---> shows the number of supporters you want to reach
!needed ---> shows how many more supporters are needed to reach said target
Progress bars on donation pages
If you add a progress bar to a donation form, it is the total amount of all donations that is counted rather than the number of submissions. If you want the counter to count numbers from another form field, enter the corresponding field's form key into the 'counter source' tab of the progress bar settings, in the 'Form key' field. This will need to be a field which only contatins numbers.
Should you want your counter to count the submissions instead of the total donation amount, you can setup a flexible form to look like a donation form. Please get in contact with support for this, we would be happy to add the relevant payment fields to your form.
Double Opt-in and Thank-You E-Mail Share Tokens
WARNING: since 2017, the tokens changed their format from
[submission:values:form_key]. We updated the generic tokens like
%confirm_url, which is now
[submission:confirm_url]. But if you used custom ones, please check them!
[submission:confirm_url] --> will show the correct link to confirm submission in the double-opt-in e-mail. If you are using double opt-in and activating the confirmation emails, be sure to use this token in it! It then becomes mandatory for supporters to click on this link (i.e. validate their email address) before their submission is confirmed. If confirmation emails are activated, no emails will be sent from your Campaignion installations for non-confirmed submissions.
[submission:values:first_name] --> will show the supporter first name
[submission:values:last_name] --> will show the supporter last name
In general, if you insert
[submission:values:form_key] and put in the field key of a webform field instead of the form_key it will pull out whatever information was inserted there. An explanation on how to find the field form key can be found here.
WARNING: The form keys of certain fields can vary from one installation to another. Be sure to check the right form key of your field in the form step of the action wizard before using any tokens.
WARNING: The token does not accept default values. If your form does not have a field with the form key referred to in your token, the token will have no value and the email will simply show an extra blank space. Make sure you take this into account in your email wording.
Special case: When the value you want is in a fieldset use the form
For example, in a donation page webform, the fieldset “Your amount” has the key "
amount" and has a field with the key “
donation_amount”. You could use it as follows:
[submission:values:first_name], for your generous gift of £
The complete list of tokens is available under the email text field, just click on the "Browse available tokens" orange text and a pop-up box should open. There, open for example the "Submission" list of token while clicking on "Submission" and drag and drop the token of your choice into one of the fields. While using the
[submission:values:?] token, be sure to replace the "?" with the form_key of your choice, as explained above.
Other potentially interesting tokens:
[node:title] --> will show the title of your action
[submission:url] --> will show the URL where the supporter took the action
[submission:date] --> will show the date of the supporter's webform submission
Share E-Mail Tokens
In the email-share settings of your action, when you scroll down the page, you'll see a token overview option named "Replacement patterns". There, you can drag and drop all the listed tokens into one of the text fields. The most important tokens for you on this page will probably be:
[share:url] ---> Link to this action
[share:sender] ---> Your name
[share:recipients] ---> The name of the person(s) you're sharing the action with.
There are no tokens for the Thank you Page for the moment.
E-Mail to Target Tokens
The Email to Target action type has it's own set of tokens.
When on the "Message" step in the wizard, you will find a selection of tokens when you scroll down to the bottom of the message editing field. When you click on a token it will automatically be added to wherever your cursor is in the text areas.
Tokens for information on the target
[email-to-target:first_name] ---> adds first name of your target
[email-to-target:last_name] ---> adds first name of your target
[email-to-target:political_affiliation] ---> adds target affiliation (if provided)
[email-to-target:salutation] ---> adds the salutation for your target
[email-to-target:title] ---> adds any titles for your target
Tokens for information on the supporter
Apart from the standard tokens, you can also add any information you have asked for in the form by simply adding the form key of that field, the logic being the same as for the thank you emails.