OptinMonster Dynamic Text Replacement API

Do you want to customize the text on your campaigns to be specific to the visitor? With OptinMonster’s incredibly powerful Dynamic Text Replacement API tool, its easy! Follow this guide to learn how to easily customize the content of your campaigns based on variables that you define on the page.

NOTE: This feature is for Advanced Users. Due to the custom nature of dynamic text replacements, at this time we do not provide support for this feature.

How Does It Work?

In its most simple form, the Dynamic Text Replacement API replaces merge tags in your campaign with matching variable identifiers on your site. When a match is found, the text is replaced. It’s as easy as that. We will explain merge tags first, and then we will list out the different methods for setting your own custom variables.

Merge Tags

Merge tags are a critical component to the Dynamic Text Replacement API. You may already be familiar with the term “merge tags”. The merge tags for this API work much the same way. You use them when creating your campaign in the OptinMonster Builder and they can dynamically change when the user sees them.

Here is an example of a merge tag used in the Dynamic Text Replacement API


The syntax is pretty easy to understand, so let’s break it down.


Every merge tag must start with two opening braces and end with two closing braces. This allows us to determine which content should be replaced inside of your campaign.


This should be the name of a custom variable you have defined. This Custom Variable is any value you have set (below, we’ll discuss how you can set this variable.) In our example below, we define a custom variable called name and give it the value of Thomas. In our merge tag example, we have referenced this by using “name” as the first string in the merge tag.

The word in green inside your merge tag should match the name of a custom variable you have defined.


Right after the word “name” in green, we see an pipe |. The pipe character ( | ) allows us to define a default value should the particular custom variable not exist on the page.

This is especially helpful if no custom variable was found, or the value set for the custom variable ended up being empty. This is completely optional. If you leave out a pipe and default value, OptinMonster will simply replace the merge tag with an empty string.


The text in blue, Visitor, is the default value that is used if the custom variable name cannot be found on the page or if the value of the custom variable name is empty.

Custom Variables

At the heart of the Dynamic Text Replacement API are custom variables. Custom variables are defined by you and contain any particular type of data you want.

The Dynamic Text Replacement API supports 3 different methods of defining custom variables (in order of priority): query arguments, cookies and JavaScript variables (advanced).

Query Arguments

The simplest way to get started with the Dynamic Text Replacement API is to use query arguments to define your custom variables. Using the example above, we want to target a custom variable called “name”. It’s as easy as adding a query argument to your URL, like this:


In the URL above, we have defined a query argument name with the value of Thomas that matches the merge tag we defined earlier. OptinMonster will inspect your URL and if it finds a match, it will replace your merge tag with the value of your query argument.

NOTE: Due to being reserved, certain terms, such as “name”, can return a 404 error when used with WordPress. So, if you have a WordPress site, then you will not be able to use certain words to pass lead data. This is because WordPress has reserved these words for their core functionality.

Here is a complete list of Reserved WordPress Terms.

It is best to add a prefix to the reserved terms to avoid getting an unexpected 404 error in WordPress. Like this:


Our Dynamic Text Replacement also supports the use of cookies as well. A cookie is a small piece of data sent from a website and stored in the user’s web browser while the user is browsing. Using our example above, much like how query arguments work, the Dynamic Text Replacement API will search for a cookie called name and replace the merge tag with the value of that cookie.

In the image below, you can see there is a cookie called name with a value of Thomas Griffin. With the example above, our merge tag would be replaced with Thomas Griffin in your campaign.

Cookie Support Dynamic Text Replacement

JavaScript Variables

For our advanced users, you can also take advantage of our complete JavaScript API for working with Dynamic Text Replacement.

Once the OptinMonster JavaScript API loads on the page and is ready to start processing, it will immediately check the page for a particular function: OptinMonsterCustomVariables. If that function is available, OptinMonster will call it and pass along the app instance as a function parameter, giving you access to the Dynamic Text Replacement API methods.

Below are two examples of ways in which you can define the function callback for the API.

Function Callback

Variable Function Callback

At the most basic level, the app method setCustomVariable takes two parameters: a key and a value. At this time, both the key and value must be strings.

You can add as many different custom variables as you would like. In the examples above, we have added the custom variable name and given it the value of Thomas.

The examples above can be added anywhere on your page, but I recommend placing it just before the closing </body> tag of your theme.

In the next section, we will look at an example of how you can use both the merge tag and the variables in your campaign.

Using Dynamic Text Replacement with the JavaScript API

Let’s consider a real world example for the Dynamic Text Replacement API. Supposed that you are creating a campaign to get people to sign up for your upcoming webinar. Customers and visitors alike are welcome to join, but you want to give your customers a bit more of a personal touch. In this case, you want to reference your customers by first name in your campaign, and you want to reference visitors with the word “there”.

Here’s what my campaign might look like in the OptinMonster Builder:

Dynamic Text Replacement Variable with Fallback

As you can see, I’ve added the merge tag {{name|there}} into the tagline of the campaign. Now that the campaign is ready for action, I’ve gone ahead and defined the custom variable name on my site to by using this code:

Sweet. Now that both the merge tags and custom variables are in place, let’s load the campaign on the page and see what appears!

Dynamic Text Replacement Variable

Excellent – the custom variable name was defined with the value of Thomas, and we see that the Dynamic Text Replacement API has worked! The merge tag {{name|there}} has been replaced with our custom variable value.

Now let’s say that I remove our custom variable definition completely from the page. When I reload the campaign, this is what appears:

Dynamic Text Replacement with Fallback

Notice now that our merge tag has been replaced with the default value “there”. That is because no custom variable was found on the page, so the Dynamic Text Replacement API simply used the default value we defined.

Let’s take this one step further. Let’s assume you’ve just added in the merge tag with no default value defined. Our campaign now looks like this in the OptinMonster Builder:

Dynamic Text Replacement with No Fallback

We see now that I have removed the default value altogether. I have also removed the custom variable definition from the page, so OptinMonster will not find a custom variable called name anywhere.

In this case, OptinMonster will simply replace the merge tag with an empty space. Once the campaign loads on the page, it will look like this:

Dynamic Text Replacement Blank Value

The merge tag has been replaced with an empty space.

API Methods

The Dynamic Text Replacement API comes with a few public methods that you can access inside of your function callback.

setCustomVariable(key, value)






Looking for more ways to extend the functionality of OptinMonster? Be sure to check to out our JavaScript events API!