---
url: >-
  https://docs.corbitaltech.dev/products/shofy-ecommerce-whatsapp-cloud-api/template-mapping/template-mapping.md
description: >-
  Automatically send WhatsApp messages when events occur in your Shofy Ecommerce
  store, such as customer sign-ups and new orders.
---

# 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 "Order Placed" or "Customer 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

***

::: warning IMPORTANT: Customer Requirement
For WhatsApp messages to be sent, **a Customer must have Phone Number** with the event.

**For Order events:**

* You **must** have a Customer or Vendor with Phone Number linked to that order
* Without a Customer association, **no WhatsApp message will be sent**
* **Example:** If you create a Order but don’t link it to any Customer, the **“Order Created”** event will not trigger a WhatsApp message

**How to ensure messages are sent:**

* Verify that customer phone numbers are valid before expecting WhatsApp messages
* Use Customer relationship fields when creating or editing records

**Customer Events** work differently — they trigger directly since the customer itself is the subject.
:::

## Creating a Template Mapping

Click the **"Create "** 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.

![create-template-mapping](../images/template_mapping_step_1.png)

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

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

**Example:** "New Order Notification" or "Welcome Message for New Customers"

**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:**

* **Customer Events:**

  * Customer Created
  * Customer Updated
  * Customer Deleted
  * Customer Email Verified

* **Order Events:**

  * Order Created
  * Order Updated
  * Order Deleted
  * Order Completed
  * Order Placed
  * Order Cancelled
  * Order Payment Confirmed
  * Order Confirmed
  * Order Product Created

* **Shippig Events:**

  * Shipping Status Changed

* **Vendor Events:**

  * Vendor Registered

* **Invoice Events:**

  * Invoice Deleted

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

**Example:** Select both "Order Placed" and "Shipping Status Changed" to send notifications for multiple scenarios.

***

**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 Customer
  :::

***

#### 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.

![create-template-mapping](../images/temp_mapping_2.png)

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

***

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

Some WhatsApp templates include images, videos, or documents 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

**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.

***

#### 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 *Customer Events:*\*

* @customer.name
* @customer.email
* @customer.phone

For **Order Events:**

* @order.id
* @order.number
* @order.total
* @order.status
* @order.created_at
* @order.date
* @order.user.name
* @order.user.email
* @order.user.phone

For **Invoice Events:**

* @invoice.code
* @invoice.amount
* @invoice.status

For **Shipping Events:**

* @shipping.name
* @shipping.email
* @shipping.phone
* @shipping.address
* @shipping.city
* @shipping.state
* @shipping.zip_code
* @shipping.country

**Example Usage:**

For a "Order Created" notification:

* Header Variable: `@order.number`
* Body Variable 1: `@order.total`
* Body Variable 2: `@order.user.name`

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

***

::: warning IMPORTANT: Merge Field

Merge field only parsed for their particular events only

**Example** Shipping merge fields only works on shipping status change event

:::

#### 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, Searchable table with these features:

* **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:

* `Order Placed` (blue badge)
* `Orde Confirmed` (blue badge)
* `+3 more` (gray badge) - Hover to see the other 3

## Tips for Success

### ✅ Best Practices

* Check that the Customer 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