MoEngage Connector - WhatsApp Channel Guide

3. Configure the WhatsApp Channel

This section walks the administrator through the complete WhatsApp setup process, from deploying the connector on Vonage Cloud Runtime to launching the first campaign. Follow the steps in order.

Step 1: Deploy the Connector on Vonage Cloud Runtime

Deploy a new instance of the Vonage MoEngage Connector from the VCR Marketplace. This is where you bind the WhatsApp account, define keyword behavior, and set the MoEngage delivery callback details.

1a. Select Your API Key and Deploy a New Instance

In the Vonage dashboard, select your API key, then click "Deploy a new instance" for the "Vonage Conversations for MoEngage” Connector application in the Cloud Runtime Marketplace.

1b. Configure the WhatsApp Account and Keyword Behavior

Complete the first part of the deployment form:

• Region: Choose the region where the connector instance will be hosted (for example, North America, Europe etc).
• Instance name: Provide a unique, concise name for this connector deployment.
• WhatsApp Account: Click "Assign account" and select the Vonage WhatsApp Business Account number to use for outbound campaign sends. This is the number end consumers will see as the sender.
• Opt-in keyword: The keyword that, when sent by an end consumer over WhatsApp, registers an opt-in. Defaults to START.
• Opt-out keyword: The keyword that, when sent by an end consumer over WhatsApp, registers an opt-out. Defaults to STOP.
• Auto-reply for opt-in request: Optional. The message sent back to the end consumer when they opt in. For example: "You have successfully opted in. Reply STOP to opt out."
• Auto-reply for opt-out request: Optional. The message sent back to the end consumer when they opt out. For example: "You have successfully opted out. Reply START to opt in."

Figure 1. Project deployment form, region, instance name, WhatsApp account, opt-in / opt-out keywords

1c. Configure the Delivery Callback and Security Fields

Scroll down to complete the second part of the deployment form:

• Default response for unknown keywords: Optional. The message sent back to the end consumer when their reply does not match the opt-in or opt-out keyword. For example: "Sorry, we did not understand your request. Reply START to opt in or STOP to opt out."
• Delivery event Signature secret (internal): The secret used to validate signed delivery callbacks from the Vonage Messages API. Use the same secret defined in the "Signed webhooks" section of your Vonage Dashboard Settings.
• MoEngage Delivery URL: The MoEngage endpoint that receives delivery status (DLR) and inbound reply events from the connector. The standard value is: https://{workspace}.moengage.com/whatsapp/vonage-v2/dlr

Note: Your specific MoEngage region URL may differ. Confirm the correct delivery URL with your MoEngage account contact or refer to MoEngage's regional endpoint documentation.

Figure 2. Project deployment form, auto-reply messages, signature secret, MoEngage Delivery URL

Click "Continue" to deploy the instance. Once the deployment completes, the VCR Marketplace will display the connector's public URL. Record this URL, you will need it in Step 2.

Step 2: Configure the Sender Profile in MoEngage

After the connector is deployed on VCR, configure the sender profile in the MoEngage dashboard so MoEngage knows how to call this connector when campaigns are launched.

2a. Navigate to WhatsApp Sender Configuration

In the MoEngage dashboard, navigate to:
Settings > Channels > WhatsApp > Sender configuration
Select the "vonage-v2" provider tab and click "+ Sender" to add a new sender profile.

2b. Fill in the Sender Profile Details

Complete the sender configuration form with the following details:

Important: The api-key and api-secret values you enter here must exactly match the credentials configured in the connector's environment (mapped to the connector's VCR_API_ACCOUNT_ID and VCR_API_ACCOUNT_SECRET variables). Mismatched credentials will cause all MoEngage send requests to fail with a 401 Unauthorized error.

Figure 3. MoEngage sender configuration, vonage-v2 provider tab with API URL, api-key, api-secret, and delivery tracking URL

Step 3: Add and Align WhatsApp Templates

Template alignment between Vonage / Meta and MoEngage is critical. WhatsApp Business Messaging requires that all outbound business-initiated messages use a pre-approved template. With v1.0, approved templates can be synced automatically from Vonage / Meta into MoEngage, so manual recreation is no longer required in most cases.

You can still add or adjust a template manually if needed, and in all cases the template configured in MoEngage must match the approved provider-side template exactly, including the template name, language, and placeholder structure.

3a. Sync Templates in MoEngage (recommended)

Rather than recreating each template by hand, you can pull all approved templates from Vonage / Meta directly into MoEngage in a single action.
In the MoEngage dashboard, navigate to:
Settings > Channels > WhatsApp > Approved templates
Click "Sync Template" in the top-right of the Approved templates view. MoEngage will fetch all approved templates registered against your Vonage WABA and add them to the list. The newest templates appear at the top of the list once the sync completes.
 

Figure 4. MoEngage Approved templates view, with the "Sync Template" action highlighted in the top right.

After syncing, verify that the template name, language, category, and placeholder structure for each synced template match the approved provider-side template before using it in a campaign.

3b. Add the Template in MoEngage (manual fallback)

If a template was not picked up by sync, or you need to register one manually, you can add it directly into the Approved templates section.

In the MoEngage dashboard, navigate to:

Settings > Channels > WhatsApp > Approved templates

Click "+ Template" to add a new template entry. In the Settings section of the template form, enter:

• Name: The exact template name as approved on the Vonage side (for example, boa_sfmc_btp).
• Service Provider: Select vonage-v2.
• Sender profile: Select the sender profile you configured in Step 2.
• Language: Select the language matching the approved template.
• Category: Select the category matching the approved template (Marketing, Utility, or Authentication).
• Template type: Select the template type (Simple default template is the standard option for most campaigns).

Figure 5. MoEngage add template form, Settings section with service provider set to vonage-v2.

3c. Match the Content Structure Exactly

In the Content section of the template form, fill in the header, body, footer, and buttons to match the approved provider-side template. Placeholder count and order must remain consistent with the approved template, otherwise campaign sends will fail.

• Header: Select the matching header type (Text, Image, Video, Document, or Location) and enter the header content (up to 60 characters for text headers).
• Body: Enter the body text with placeholders in the {{1}}, {{2}}, format. Up to 1024 characters.
• Footer: Optional, up to 60 characters.
• Buttons: Add Quick reply or Call to action buttons as defined in the approved template.

Figure 6. MoEngage template Content section, Header, Body, Footer, and Buttons.

Note: MoEngage does not fully validate template correctness at save time. Any mismatch between the template structure in MoEngage and the approved template on the Vonage / Meta side will cause campaign sends to fail at delivery with a "1022, Invalid template or template parameters" error. See the Troubleshooting section for guidance.

Step 4: Configure Personalization

Once a sender and a template are in place, personalization controls how MoEngage user attribute data is injected into the template placeholders at send time.

4a. Select Sender and Template in the Campaign

When creating a new WhatsApp campaign in MoEngage (Campaigns > WhatsApp (One-time) > Create), the campaign wizard's Content step prompts you to choose the sender profile and the approved template, then fill in the placeholders that template exposes.

Figure 7. Campaign Content step, Select sender and Select template with placeholder inputs revealed.

4b. Map Placeholder Inputs

For each placeholder ({{1}}, {{2}}, and so on), you can map a value in one of three ways:

• Type fixed text into the input field for a static value across all recipients.
• Type the "@" character to open the personalization picker and inject a dynamic MoEngage data field (user attribute, campaign attribute, event attribute).
• Use a combination of static text and a personalized attribute (for example, "Hi @FirstName, ").

Figure 8. Placeholder personalization, typing @ opens the personalization picker.

4c. Select the Attribute to Inject

In the WhatsApp Personalization dialog, search for and select the user attribute (or other supported data field) that should populate the placeholder. The selected attribute will resolve dynamically at send time for each user in the campaign audience.

Figure 9. WhatsApp Personalization dialog, Data personalization tab with attribute search.

4d. Set Fallback Behavior

For each personalized placeholder, define what should happen if the attribute value is missing for a given user. Three fallback options are available:

• No fallback: Send the message with the placeholder left blank, or as configured by MoEngage.
• Do not send campaign: Skip this user entirely; the message is not sent to them.
• Replace text: Substitute the missing value with a fixed fallback string (for example, "Mr./Mrs.").

Figure 10. Choose Fallback options with "Replace text" selected.

Click "Done" to apply the personalization configuration.

Step 5: Build and Launch a Campaign

With the connector deployed, the sender configured, the template added, and personalization mapped, the final step is to build the campaign in MoEngage's campaign wizard, select the audience, and publish.

5a. Create a New WhatsApp Campaign

In the MoEngage dashboard, navigate to:

Campaigns > WhatsApp (One-time) > Create

5b. Configure Target Users

In the Target users step, configure:

• Campaign name: A descriptive name for the campaign.
• Campaign tags: Optional tags for organization (for example, "promotional").
• Select audience: Choose "All users" or "Filter users by" to apply segment filters.
• Exclude Users: Optionally exclude segments from the campaign.
• Send campaign to users ignoring Opt-in preference: Leave unchecked to respect each user's opt-in status. Only enable this option if your compliance policy explicitly permits it.

Figure 11. Campaign Target users step, audience selection and opt-in handling.

Test send tip: For end-to-end verification before going to a full audience, you can scope the audience filter to a single test user (for example, filter by a unique user identifier or email matching your test account). This sends only to your test user, letting you confirm delivery before publishing to the full audience.

Click "Show count" to verify the estimated audience size, then click "Next".

5c. Configure Content

In the Content step, select the sender and the approved template, then map placeholder inputs and fallbacks as described in Step 4. The right-hand preview pane shows a live preview of the message as it will appear in WhatsApp.

5d. Schedule and Publish

In the Schedule and goals step, configure the send schedule (immediate, scheduled for a future date and time, or recurring), set any conversion goals or A/B test variants, and review the campaign summary.

Click "Publish" to launch the campaign. MoEngage will begin posting send requests to the connector's webhook endpoint, which will dispatch them through the Vonage Messages API.

5e. Monitor Delivery in Campaign Analytics

Once the campaign is live, the connector translates Vonage delivery status callbacks (submitted, delivered, read, rejected) into MoEngage's DLR format (sent, delivered, read, failed) and posts them to the MoEngage Delivery URL configured in Step 1c. These events flow into MoEngage's campaign analytics in near real time and are visible in the standard campaign reporting views:

• Navigate to: Campaigns > [your campaign] > Analytics
• Delivery funnel: Track the count of users at each stage (sent, delivered, read), and the count of failed deliveries with their failure reason.
• Failed delivery reasons: For rejected messages, the connector includes the Vonage provider error code and description in the DLR payload, so failures surface in MoEngage analytics with a meaningful reason (for example, "1022, Invalid template or template parameters") rather than a generic failure.
• Reply events: Supported template button replies (Quick reply, Call to action) are forwarded to MoEngage as reply events and appear under the campaign's engagement metrics.
• Opt-out attribution: STOP and opt-out replies are synced back to the MoEngage contact record, automatically suppressing those users from subsequent campaign sends.

There is typically a few seconds of latency between Vonage delivery and MoEngage analytics updates, depending on the carrier and WhatsApp's status callback timing. If DLR events do not appear in analytics within a few minutes of send, see the Troubleshooting section for guidance on verifying the MoEngage Delivery URL and signature secret.

4. Troubleshooting and Log Access

If WhatsApp messages are not being delivered or the campaign is not behaving as expected, start with the following checks.

Initial Checks

• Verify credentials: Confirm that the API URL, api-key, and api-secret entered in MoEngage's sender configuration exactly match the connector's configured credentials.
• Verify the WhatsApp business number: Confirm the WABA number entered in MoEngage's sender configuration matches the WhatsApp account assigned to the connector instance in Step 1.
• Verify the MoEngage Delivery URL: Confirm the MoEngage Delivery URL configured on the connector matches the URL displayed in MoEngage's sender configuration delivery tracking section.
• Verify template alignment: Confirm the template name, language, category, and placeholder structure in MoEngage exactly match the approved template on the Vonage / Meta side.
• Check opt-in status: Confirm that the test recipient has not previously opted out. End consumers who have replied STOP are suppressed from future sends.

End-to-End Message Lifecycle, Tracing a Single Request

Every WhatsApp campaign send follows four stages. Each stage has its own log source. When troubleshooting, work through the stages in order, a failure at any stage prevents subsequent stages from executing.

Stage 1: MoEngage Triggers the Campaign Send

Where to look: MoEngage Dashboard, Campaign Analytics

When a campaign is published or scheduled, MoEngage's orchestrator posts a send request to the connector's send endpoint for each user in the audience. The MoEngage Campaign Analytics view captures the outbound request count and the initial response status from the connector.

Stage 2: Connector Receives and Dispatches

Where to look: Vonage Cloud Runtime, Instances, Your Instance, Logs

The connector instance running on Vonage Cloud Runtime receives the send request from MoEngage. The VCR instance logs capture the incoming request, the validated payload, the queueing event, and the outbound dispatch to the Vonage Messages API.

Key log lines to look for:

• POST /webhooks/message-dispatcher, confirming the connector received the request from MoEngage.
• execute { template: { name: ... } }, confirming the connector parsed the template payload.
• Sending POST to .../queue/.../enqueue, confirming the message was queued.
• Sending WhatsApp via Vonage: msg_id=..., confirming the message was dispatched to the Vonage Messages API.

Figure 12. Connector logs showing dispatch from message-dispatcher webhook through queue enqueue to WhatsApp send.

Stage 3: Vonage Messages API Delivers the Message

Where to look: Vonage Customer Dashboard, Message Logs

Vonage delivers the WhatsApp message through the Messages API. The delivery event, including message status, recipient, and any provider error codes, appears in the Vonage Customer Dashboard message logs.

What to check:

• Message status: Look for the outbound message record. A "delivered" or "read" status confirms the message reached the recipient. A "submitted" status means the message was accepted by Vonage but not yet delivered.
• Rejection or failure: A "rejected" status indicates the message was rejected by Vonage or Meta before delivery. Common causes include invalid template parameters, recipient not opted in, or recipient number invalid.
• Error codes: If the message was rejected, note the provider error code and reference the Vonage Messages API error documentation for details.

Stage 4: DLR Posted Back to MoEngage

Where to look: Vonage Cloud Runtime, Instances, Your Instance, Logs; and MoEngage Campaign Analytics

After dispatching the message, the connector receives status callbacks from the Vonage Messages API. These are translated into MoEngage's DLR format and posted to the MoEngage Delivery URL. The status mapping is:

For rejected messages, the connector includes the Vonage provider error code and description in the MoEngage DLR payload so that MoEngage analytics can surface the failure reason.

Figure 13. Connector logs showing a rejected message status callback being received from Vonage.

Figure 14. Connector logs showing the corresponding failed delivery report posted to MoEngage.

Common Error Scenarios

5. How to Get Help

Best way (recommended): Vonage Help Center https://api.support.vonage.com/hc/en-us/requests/new
Select the form titled "Using Vonage Connectors" so the ticket is routed directly to the MoEngage Connector support group.

What to include (for faster resolution):

Note: For issues that are specific to the MoEngage platform itself (campaign builder behavior, MoEngage user attribute setup, audience segmentation logic), contact MoEngage Support directly. MoEngage platform issues are outside Vonage's support scope.

6. For End Users, Campaign Delivery Experience

End users do not need to perform any configuration. Once the administrator has completed the setup in Section 3, the Vonage MoEngage Connector handles WhatsApp campaign delivery transparently. From the end user's perspective:

• The user receives a WhatsApp message from the brand's WhatsApp Business Account number. The message uses an approved WhatsApp template and may include personalization (their name, account details, and so on).
• If the user replies STOP (or the configured opt-out keyword), the connector registers the opt-out and syncs this status back to MoEngage. The user will receive a confirmation auto-reply, if configured, and will be excluded from all future campaign sends until they opt back in.
• If the user replies START (or the configured opt-in keyword), the connector registers the opt-in and syncs this status back to MoEngage. The user will receive a confirmation auto-reply, if configured.
• Any other free-text reply may receive the configured default response, but does not trigger any campaign-side action.
• Replies on supported template buttons (quick reply, call to action) are forwarded to MoEngage as reply events for use in MoEngage's campaign analytics and journey flows.

The Vonage MoEngage Connector operates entirely behind the scenes. End users interact only with the brand's WhatsApp presence in their standard WhatsApp client.