Symptom or Need

You may experience difficulties when launching mass WhatsApp campaigns due to inconsistencies in the configuration or synchronization of templates between Meta Business and the Wolkvox campaign system.

The most common issues that may arise are:

• The template approved in Meta does not appear available in the Wolkvox platform.
• The system displays errors such as "incomplete variables" or "misconfigured variables" when scheduling the campaign shipment.
• Dynamic variables are not replaced correctly within the message.
• Customers receive messages with codes like {{1}} instead of the corresponding personalized data.
• The campaign is rejected, stops automatically, or presents failures during execution.

Context / Scenarios

This issue occurs during the integration between WhatsApp Business Manager (Meta) and the Wolkvox Campaigns module, specifically when:

• Dynamic variables are used: You have designed a template in Meta that includes dynamic placeholders (variables like {{1}}, {{2}}) to personalize the message with specific data, such as name, date, or order ID.

         Template Example: “Hello {{1}}, we remind you that your appointment is on {{2}} at {{3}}.”

        During campaign execution, the system replaces these variables with the corresponding data for each contact based on the                 information contained in the database.

• Pending synchronization: The template has already been approved by Meta, but the changes have not yet been updated in the Wolkvox connector.
• Data Mapping: When configuring the campaign, the system requires "linking" or mapping the WhatsApp template variables with the corresponding columns or fields in your database.
• Campaign Execution: An attempt is made to launch the mass mailing without the system having correctly processed the relationship between the synchronized template and the campaign's dynamic fields.

Response / Solution

To avoid inconveniences when using variables in mass WhatsApp campaigns, it is recommended to follow these steps:

• Template Creation in Meta:

1. Create the template in WhatsApp Business Manager.
2. Include variables in the correct format ({{1}}, {{2}}).
3. Submit the template for approval. Templates must be approved by Meta before they can be used in automated campaigns.

• Synchronize your templates with Wolkvox

If your template is new or was recently edited and approved in Meta, you must synchronize it so it becomes available in the Wolkvox Manager configuration: 

1. Log in to Manager, go to: Configuration > Omni Channel > WhatsApp.
2. Locate the WhatsApp connector you wish to configure.
3. Click the pencil icon (Edit) of your WhatsApp connector.
4. In the upper right corner, open the three-dot menu and select Configure templates.
5. The list of available templates will be displayed.
6. Click the Synchronize templates button. Your template will now appear in the list. 

• Link the Campaign Variables

To ensure the system correctly replaces data in each variable {{1}} or {{2}}, do the following:

1. In Manager, go to Campaign Template Configuration and open the WhatsApp tab.
2. Create or edit the required template. It is recommended to create a new one to avoid configuration conflicts.
3. Once the template is created or selected, go to the Content section and define the name.
4. Mapping: You will see the Meta template fields. There, you must type the Wolkvox variable inside curly brackets { }.

         Example: If in Meta your template says: “Hello {{1}}, we have great news for you...”

         Wolkvox variable declaration in the campaign template: {customer_name}.

         The message preview should display as follows: "Hello! {customer_name}, we have great news for you..."

    5. Configure the campaign variables (you can consult these in the help section within the configuration).

    6. Fill in the required fields and select the WhatsApp connector where the Meta templates were previously synchronized.

    7. Insert the campaign variable into the Variable Value field corresponding to the WhatsApp template. 

• Prepare your Database

Before running the campaign, verify that the database loaded for the campaign contains the column or field corresponding to the configured variable (e.g., customer_name), as the system will pull the replacement value from there.

• Perform a Real Test

Before the mass mailing:

1. Perform a test send to an internal number.
2. Validate that the variables are replaced correctly.
3. Verify that the template used is the correct one.

Possible Causes

• Lack of synchronization: The template exists in Meta but has not been synchronized with Wolkvox.
• Typing error: Curly brackets { } were not entered, the field name in the database was recorded incorrectly, or the number of variables in the campaign does not match the template.
• Data structure error: The loaded database does not contain the required columns to replace variables.
• Incorrect template name: The name used in the campaign does not exactly match the one registered in Meta.
• Use of unapproved templates: The template is still in a "Pending" or "Rejected" status.

Considerations / Recommendations

• Issues with an edited template?: If a template gives you an error after being modified, we recommend creating a new one with a different name. Meta sometimes keeps old versions in cache which causes conflicts.
• Global Variables: Remember that for the system to recognize a dynamic field, it must always be inside brackets: {data}.
• Clean Database: Avoid blank spaces or special characters in the column headers of your database.

Best Practices

• Synchronize templates after every approval in Meta.
• Document the variables used in each template.
• Use clear and standardized template names.
• Maintain a test template for internal validations.

Pre-Campaign Validations

Before launching a campaign, validate:

• Template approval in Meta.
• Template synchronization in Wolkvox.
• Correct configuration of variables.
• Database is populated with required fields.
• Successful test send.