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 stuff like customise the email 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 little 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 use tokens from the second page of your action and onward. 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. So 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
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 your submission in the double-opt-in e-mail. While using a the double opt-in and activating the confirmation emails, be sure to use this token in it! Then, it will be mandatory for the supporters to click on this link (i.e. validate their email address) for their submission to be 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. A small explanation on how to find the field form key might 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: If you do not have any field with the form key form_key in the webform, the token will have no value and the email will simply show white space.
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 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
Our newest action type e-mail to target has it's own new 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.