Mapping WhatsApp Template Placeholders to Contact Fields

WhatsApp templates carry placeholders — slots like {{1}}, {{2}} that get filled per recipient. When you use a template in a campaign, AI Engage asks you to map each placeholder to a contact field, so the recipient's own data (first name, city, company…) is substituted at send time. This guide covers mapping placeholders in the campaign builder and filling in sample values to preview and test.

Before you start#

You map placeholders while building a WhatsApp campaign, after you've picked a template. The panel reads the template's registered placeholders and offers your contact module's fields to map them to. For the full campaign flow, see Send a WhatsApp Campaign; to author templates, see WhatsApp Templates.

Map each placeholder#

In the campaign builder's right-rail Configure message panel you'll see the instruction “Map each placeholder to a contact field. Values are substituted per recipient.” Under Body placeholders (with a count badge), there's one row per placeholder position:

Each row is labelled with its position — for example Placeholder {{1}} — and, where known, what it was originally called in the template (e.g. “originally {{first_name}}”), so you can tell the slots apart.
Open the field dropdown (“Pick a contact field”), search if needed, and choose the contact field whose value should fill that placeholder.
Repeat for every position. A red asterisk marks each mapping as required.

The Continue to Review button stays disabled until every placeholder is mapped — this prevents sending a message with an empty slot, which WhatsApp and Meta reject.

💡

The panel seeds itself from the template's stored mapping — the original placeholder-to-field pairing saved when the template was registered — so common fields are often pre-filled. If a template's stored mapping is missing or incomplete, AI Engage reads the placeholders directly from the message body so nothing is silently skipped. You can override any pre-filled choice to point a position at a different field.

⚠️

If the template has no variables, the panel simply says “This template has no body placeholders — nothing to map.” and you can continue. Header media (an image or file in the template header) isn't configurable here — Meta locks it to the file the template was approved with, so every recipient gets that same media.

Preview and test with sample values#

Before sending, the Preview & test step shows a Fill in placeholders card so you can see and test the personalised result. It has one row per placeholder, with the field's friendly label leading and the raw token (e.g. {{first_name}}) shown as a small reference chip. The note reminds you: “Filled automatically for each contact when you send. Add a sample value so you can preview and test it.”

Status pill — at the top of the card, it reads “N to fill” while any value is blank and flips to “Ready to send” once all are filled.
Per-row status — each row shows “Needs a value” (highlighted) until you enter something, then “Looks good”.
Field type — a placeholder mapped to a pick-list field shows a searchable dropdown of that field's options; anything else is a free-text input where you type a sample value.

These sample values are only for previewing and the test send — at the real send, each placeholder is filled from the individual contact's data via the mapping you set.

✅

Always send yourself a test after filling the sample values. It confirms your field mapping produces sensible text before the message goes to your whole audience.

Good to know#

Position order matters — placeholders follow their order of appearance in the message body, and a repeated placeholder (the same {{1}} used twice) is mapped once and filled with the same value everywhere it appears.
Fields come from Contacts — the dropdown lists the contact module's own fields, which are the keys the send pipeline looks up for each recipient.

Was this article helpful?

Ready to implement this?

OpenAI Engage and apply what you just learned to your own workspace.

Open AI Engage CRM