Complete overview of the Flow Builder
Merge fields are a powerful tool to personalise your communications and customer journeys, using either the customer data from your systems of record, from external systems (weather services, traffic services etc.) or from the outputs of a node (for example, the recipient’s mobile number from the Inbound message trigger node). In this article, you’ll learn about merge fields and ways you can use them to personalise messages and customer journeys.
What are merge fields?
Merge fields are dynamic values that are replaced with the recipient-specific value when a flow goes live. The recipient-specific value is determined by the data brought into the flow. A merge field can be identified through its bold appearance, like this: firstName.
For instance, to personalise a message using the customer's first name, your message could use the merge field: firstName. When a flow is live, the merge field references all the data stored against the corresponding firstName field in your systems, which is retrieved by a prior node in your flow. The recipient would receive a message with the merge field replaced with their name:
Using merge fields in flows
You can view merge fields available to reference via the merge field pop up, or through the data explorer in the merge field tab. You can either search, or traverse prior nodes to find the merge field you want to reference. Once found, simply click to either insert (in the merge field pop up) or copy to clipboard (in the merge field tab).
Important considerations when viewing available merge fields:
Each node will only display merge fields generated by previous nodes along the same branch. You cannot reference merge fields from a node on a separate branch.
You can only select merge fields from nodes if they have outputs and are on the 'common path' on the current node.
Merge field pop up
The merge field pop up is a handy way to search and insert merge fields straight into an input field. It also easily lets you know whether you can use a merge field in that particular field.
How to use the merge field pop up
- Click the merge field button. A search bar will appear.
- Type a value in the search bar. The value will only be searched against the path of the merge field itself, not the description nor example.
- Click the merge field you want to use to insert it, and voilà!
Merge field tab: Quick search
The merge field pop up is a handy way to search and insert merge fields straight into an input field. It also easily lets you know whether you can use a merge field in that particular field.
How to use the search bar
- Type a value in the search bar. The value will only be searched against the merge field itself, not the description nor example.
- Click to copy the merge field to your clipboard, and paste in the desired field.
Merge field tab: Explorer
The merge field explorer displays merge fields that can be referenced from nodes previous to this node.
How to use the merge field explorer
- In the first column, click on a node item to view the merge fields within. This column displays all the nodes you can copy merge fields from, in respect to this node's position in the flow.
- Click through the levels of data to select from, as indicated by a forward arrow icon. The merge field is indicated by a plus icon.
- Click to copy the merge field to your clipboard, and paste into desired field within the node's configuration settings.
Further applications & considerations
Merge fields are not limited to message bodies. They can also be used in other fields across the Flow Builder, such as criteria split fields and recipient fields.
Merge fields affect character count
The character count in the message body will not accurately reflect the rendered version of the merge fields. For example, firstName can render as Lam (3 characters) or Maddie (6 characters).
Using merge fields with arrays
When using merge fields with arrays, Lumary's Engaugement Console currently defaults to rendering the first item in the array retrieved.
Use merge fields with arrays with caution, as you can't guarantee the array index exists in the database.
Using merge fields with a blank or non-existent value
If a merge field value is blank or non-existent in your data extension, it will simply render blank in the message to the recipient.
The exception to this is when you use merge fields for the sender email address or phone number. If the data for those fields does not exist, the message will not be sent.
Conditional logic & loops (Advanced)
Merge fields operates on the simple templating language called Handlebars. This templating language uses expressions, wrapped in double curly braces, to access values passed into the template. It supports conditional logic, loops, and helpers, enabling you to display specific blocks of information based on defined criteria.
For example, Betty, who had a timestamp against her visit, would receive a different message to Cody, who didn't.
If-else {{#if}}
If-else statements let you conditionally render blocks based on if-else logic arguments; if this, then do this. The {{#if}} block argument checks whether a value exists in the block, as opposed to a return of false, undefined, null, “”, 0 or {}.
Hey {{firstName}},
Thanks for your recent visit at Acme
{{#if webhookTrigger.date}}
on {{webhookTrigger.date}}
{{/if}}.
How did we go?
You can also use {{else}} inside of {{#if}} statements to determine what block will render if the initial{{#if}}block returns a false value.
Hey {{firstName}},
Thanks for your recent visit at Acme
{{#if webhookTrigger.date}}
on {{webhookTrigger.date}}
{{else}}
with our team
{{/if}}.
How did we go?
The example above would render differently if the date stamp was recorded or not.
Unless {{#unless}}
You can use the unlesshelper as the opposite of the if helper. Its block will likewise be rendered if the expression returns a false, undefined, null, “”, 0 or {}.
{{#unless hasActiveSubscription}}
Hey {{firstName}},
Remember, your subscription has expired. Renew now to continue enjoying our services!
{{/unless}}
For instances where more complex conditional logic is required, see Criteria Split Node.
For more information on using conditional logic with Handlebars, see here.