---
url: >-
  https://docs.corbitaltech.dev/products/concord-crm-whatsapp-cloud-api/template-mapping/template-mapping.md
---
# Template Mapping

## What is Template Mapping?

Template Mapping allows you to automatically send WhatsApp messages when certain events occur in your CRM system. For example, you can send a welcome message when a new contact is created, or notify your team when a deal is won.

Think of it as connecting your CRM events (like "Deal Won" or "Contact Created") to pre-configured WhatsApp message templates, so messages are sent automatically without any manual work.

## Why Use Template Mapping?

✅ **Save Time** - Automate repetitive WhatsApp messages\
✅ **Stay Connected** - Never miss important customer touchpoints\
✅ **Personalize Messages** - Use dynamic data from your CRM in messages\
✅ **Be Consistent** - Ensure every customer receives the same professional messages

***

### Viewing Your Template Mappings

When you navigate to the Template Mapping section, you'll see a table listing all your configured mappings. The table displays:

* **Name** - A friendly name you gave to this mapping
* **Event Types** - Which CRM events trigger this message (shown as badges)
* **Template** - Which WhatsApp template is used
* **Status** - Whether the mapping is active or inactive

#### Empty State

If you haven't created any mappings yet, you'll see a helpful message with a button to create your first mapping.

***

::: warning IMPORTANT: Contact Requirement
For WhatsApp messages to be sent, **a contact must be associated** with the event.

**For Company, Deal, Activity, Document, Note, and Call events:**

* You **must** have a contact linked to that record
* Without a contact association, **no WhatsApp message will be sent**
* **Example:** If you create a Deal but don’t link it to any Contact, the **“Deal Created”** event will not trigger a WhatsApp message

**How to ensure messages are sent:**

* Always add/link contacts to Companies, Deals, Activities, Documents, Notes, and Calls
* Verify that contact phone numbers are valid before expecting WhatsApp messages
* Use contact relationship fields when creating or editing records

**Contact Events** work differently — they trigger directly since the contact itself is the subject.
:::

## Creating a Template Mapping

Click the **"Create Mapping"** button to start creating a new mapping. You'll work through two simple tabs:

### Tab 1: Basic Info

This is where you configure the core settings for your mapping.

#### 1. **Name** (Required)

Give your mapping a descriptive name so you can easily identify it later.

**Example:** "New Deal Notification" or "Welcome Message for New Contacts"

**Tip:** Use clear names that describe what the mapping does.

***

#### 2. **Event Types** (Required)

Select one or more events that will trigger this WhatsApp message.

**Available Events:**

* **Contact Events:**

  * Contact Created
  * Contact Updated
  * Contact Deleted

* **Company Events:**

  * Company Created
  * Company Updated
  * Company Deleted

* **Deal Events:**

  * Deal Created
  * Deal Updated
  * Deal Deleted
  * Deal Stage Changed
  * Deal Won
  * Deal Lost

* **Activity Events:**

  * Activity Created
  * Activity Updated
  * Activity Deleted

* **Document Events:**

  * Document Created
  * Document Updated
  * Document Deleted

* **Note Events:**

  * Note Created
  * Note Updated
  * Note Deleted

* **Call Events:**
  * Call Created
  * Call Updated
  * Call Deleted
  * Missed Incoming Call

**You can select multiple events** - The same template will be sent for any selected event.

**Example:** Select both "Deal Won" and "Deal Stage Changed" to send notifications for multiple scenarios.

***

::: tip 📱 IMPORTANT: Phone Number Priority
When a contact has **multiple phone numbers**, the system uses the following priority to decide which number receives the WhatsApp message:

**Priority Order:**

1. **Mobile** (Highest Priority)

   * If any *Mobile* numbers exist, the **first Mobile number** is used

2. **Work** (Second Priority)

   * Used only if no Mobile numbers exist
   * The **first Work number** is selected

3. **Other** (Lowest Priority)
   * Used only if no Mobile or Work numbers exist
   * The **first Other number** is selected

**Examples:**

* **Contact has:** 2 Mobile, 1 Work\
  **WhatsApp sent to:** First Mobile number

* **Contact has:** 0 Mobile, 3 Work, 1 Other\
  **WhatsApp sent to:** First Work number

* **Contact has:** 0 Mobile, 0 Work, 2 Other\
  **WhatsApp sent to:** First Other number

**Best Practices:**

* Save the primary WhatsApp number as **Mobile**
* Order phone numbers by importance when adding multiples
* Ensure at least one valid phone number exists for every contact
  :::

***

#### 3. **WhatsApp Template** (Required)

Choose which WhatsApp message template to use for this mapping.

**What you'll see:**

* A dropdown list of all your available WhatsApp templates
* Template names as they appear in your WhatsApp Business account

**If no templates appear:**
This means you need to sync your WhatsApp templates first. Contact your administrator or check the template sync settings.

***

#### 4. **Active Status**

Use the toggle switch to activate or deactivate this mapping.

* **ON (Active)** - Messages will be sent when events occur
* **OFF (Inactive)** - Events will be ignored, no messages sent

**Tip:** Keep mappings inactive while testing or editing them. Activate only when you're ready to send live messages.

***

### Tab 2: Variables & Files

After selecting a template, click **"Next"** to configure variables and upload files. This tab customizes your message content.

**What you'll see depends on your template:**

***

#### File Upload (if your template includes media)

Some WhatsApp templates include images, videos, documents, or audio files. If your template has media, you'll see a file upload area.

**Supported File Types:**

* **Images:** JPG, JPEG, PNG

  * Maximum size: 5 MB

* **Videos:** MP4, 3GP

  * Maximum size: 16 MB

* **Documents:** PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX

  * Maximum size: 100 MB

* **Audio:** MP3, OGG, AAC, AMR
  * Maximum size: 16 MB

**How to upload:**

1. Click the upload area or drag and drop your file
2. The system validates file type and size automatically
3. A preview appears (for images) or filename confirmation (for documents)

**To replace a file:**
Simply upload a new file - it will replace the previous one.

**To remove a file:**
Click the remove/clear button next to the file preview.

***

#### Message Variables (Dynamic Content)

WhatsApp templates often include **variables** (placeholders) that get replaced with real data from your CRM.

**What are variables?**\
Variables are marked with double curly braces like `{{1}}`, `{{2}}`, etc. in your WhatsApp template. They allow you to insert personalized information into messages.

**Example:**\
Template text: `Hello {{1}}, your deal {{2}} has been won!`

When sent, it becomes: `Hello John Smith, your deal Website Redesign has been won!`

***

#### Filling in Variables

You'll see input fields for each variable in your template, organized by section:

**Header Variables** (if template has a text header)

* Usually 1 variable for the header section

**Body Variables** (main message content)

* Can have multiple variables ({{1}}, {{2}}, {{3}}, etc.)

**Footer Variables** (if template has a footer)

* Additional variables for footer text

***

#### Using Merge Fields (Smart Variables)

Instead of typing static text, you can insert **merge fields** - dynamic data from your CRM that updates automatically.

**How to use merge fields:**

1. Click inside any variable input field
2. Type the **@** symbol
3. A dropdown menu appears with available merge fields
4. Select the field you want to insert

**Available Merge Fields depend on the event type you selected:**

For **Contact Events:**

* @contact.first_name
* @contact.last_name
* @contact.email
* @contact.phone
* @contact.company_name
* And more...

For **Deal Events:**

* @deal.name
* @deal.amount
* @deal.stage
* @deal.expected_close_date
* @deal.owner.name
* And more...

For **Activity Events:**

* @activity.title
* @activity.type
* @activity.due_date
* @activity.assigned_to
* And more...

**Example Usage:**

For a "Deal Won" notification:

* Header Variable: `@deal.owner.name`
* Body Variable 1: `@deal.name`
* Body Variable 2: `@deal.amount`

The message will automatically pull the real deal owner, deal name, and amount when sent.

***

#### Live Preview

As you fill in variables and upload files, **the preview panel on the right side** shows how your WhatsApp message will look!

The preview includes:

* **WhatsApp chat background** (light or dark mode)
* **Media preview** (images, videos, document links)
* **Message text** with variables replaced by sample data
* **Message buttons** (if your template has buttons)

**Tip:** Use the preview to verify your message looks professional before saving.

***

### Navigation Buttons

**At the bottom of the form:**

**On Tab 1 (Basic Info):**

* **Cancel** - Discard changes and return to the listing page
* **Next** - Move to Tab 2 (Variables & Files)

**On Tab 2 (Variables & Files):**

* **Previous** - Go back to Tab 1
* **Save** - Create the mapping (only enabled when all required fields are filled)

## Managing Existing Mappings

### Viewing the Mappings Table

Your mappings appear in a sortable, filterable table with these features:

#### **Filtering**

Use the view filters to show:

* **All Configurations** - Every mapping
* **Active** - Only active mappings
* **Inactive** - Only inactive mappings

#### **Sorting**

Click any column header to sort by:

* Name (alphabetically)
* Event types
* Creation date
* Status

#### **Searching**

Use the search box to quickly find mappings by name.

***

### Editing a Mapping

1. Find the mapping in the table
2. Click the **Edit** action (pencil icon) in the Actions column
3. Make your changes in the form (same as creating)
4. Click **Save** to update

**Note:** When editing, you can keep the existing file or upload a new one. You don't need to re-upload if you're just changing variables.

***

### Deleting a Mapping

1. Find the mapping in the table
2. Click the **Delete** action (trash icon) in the Actions column
3. Confirm the deletion in the popup dialog
4. The mapping is permanently removed

**Warning:** Once deleted, the mapping cannot be recovered. Events will no longer trigger WhatsApp messages for this configuration.

***

### Activating/Deactivating Mappings

You can quickly enable or disable mappings without editing them:

1. Select one or more mappings (check the boxes)
2. Use the bulk actions dropdown:
   * **Mark as Active** - Enable selected mappings
   * **Mark as Inactive** - Disable selected mappings

**Or** edit individual mappings and toggle the Active switch.

## Understanding Event Type Badges

In the table, event types appear as **colored badges**:

* **Blue badges** - Individual event types
* **Gray "+X more" badge** - Indicates additional hidden events

**Hover over** the "+X more" badge to see all event types in a tooltip.

**Example:**
If a mapping has 5 event types, you'll see:

* `Deal Won` (blue badge)
* `Deal Lost` (blue badge)
* `+3 more` (gray badge) - Hover to see the other 3

## Tips for Success

### ✅ Best Practices

* Check that the contact has at least one phone number (Mobile, Work, or Other type)

3. **Wrong Phone Number Priority**
   * WhatsApp is being sent to an incorrect/inactive number
   * Solution: Check the phone number type priority (Mobile > Work > Other)
   * Ensure the first Mobile number is the correct WhatsApp number
   * Reorder phone numbers if needed to prioritize the active WhatsApp number

4. **Mapping is Inactive**
   * The template mapping is turned off
   * Solution: Check the Active toggle is ON in the mapping settings

5. **Use merge fields wisely** - Always use dynamic merge fields instead of hardcoded names or values

6. **Check preview** - Always verify the preview before saving to catch formatting issues

7. **Keep mappings organized** - Don't create duplicate mappings for the same events

8. **Monitor file sizes** - Large video/document files may take time to send, use appropriately

### ⚠️ Common Mistakes to Avoid

* **Missing required fields** - The Save button won't work until all required fields are filled
* **Wrong file types** - Match your file type to what the template expects (image vs document)
* **Empty variables** - Don't leave variable fields blank if they're required
* **Testing with active mappings** - Always deactivate before testing to avoid sending messages to real customers