MoEngage Connector - WhatsApp Channel Guide - Version 2.0

Table of Contents

1. Introduction

2. Prerequisites

3. Configure the WhatsApp Channel, Conversational Connect Mode

4. Configure the WhatsApp Channel, Standalone Mode

5. Post-Setup Steps (Both Modes)

6. Troubleshooting and Log Access

7. How to Get Help

8. For End Users, Campaign Delivery Experience

1. Introduction

This guide walks you through configuring the Vonage MoEngage Connector for the WhatsApp channel in version 2.0. Version 2.0 introduces two operating modes selectable at provisioning time: Standalone mode (one-way broadcast through the Vonage Messages API, functionally equivalent to v1.0) and Conversational Connect mode (two-way messaging through Conversational Connect, enabling bot flows and live agent handoff). The setup steps differ between modes; this guide provides both.

You will deploy the connector instance on Vonage Cloud Runtime, choose an operating mode, complete the connector admin panel configuration (bearer token generation and delivery URL setup), configure the Vonage sender in MoEngage, sync your approved WhatsApp templates, set up personalization, and launch your first WhatsApp campaign. End-consumer replies matching the configured opt-out keyword (default: STOP) are processed by the connector and synced back to MoEngage in both modes. For an overview of the connector including architecture, key benefits, and the SMS channel, refer to the main Vonage Conversations for MoEngage knowledge base article.

2. Prerequisites

Before you begin, make sure you have the following:

• A Vonage API account with an API Key and a provisioned WhatsApp Business Account (WABA) sender.
• At least one approved WhatsApp template registered against your WABA sender (Standalone mode), or against your Conversational Connect account (Conversational Connect mode).
• Access to the Vonage Customer Dashboard (https://dashboard.nexmo.com/private/dashboard) and Vonage Cloud Runtime (https://developer.vonage.com/en/cloud-runtime).
• Admin access to the MoEngage dashboard to configure sender profiles, templates, and campaigns.

For Conversational Connect mode, additionally:

• A Conversational Connect account with the WhatsApp channel already configured (WhatsApp Business number linked to your Conversational Connect account).
• Ability to access the Conversational Connect Developer Portal to create an application and configure a webhook signing secret.

Note: If you do not yet have a WhatsApp Business Account (WABA) provisioned with Vonage, contact your Vonage Customer Success Associate (CSA) or Account Manager to begin the WABA onboarding process. WABA provisioning is a prerequisite to deploying this connector and is handled outside of the VCR Marketplace flow.

3. Configure the WhatsApp Channel, Conversational Connect Mode

This section walks you through the complete WhatsApp setup for Conversational Connect mode. If you are deploying in Standalone mode, skip to Section 4.

Step 1: Create an Application in Conversational Connect

In the Conversational Connect Developer Portal, navigate to Applications and click "+ Create a new application".

Figure 1. Creating a new application in the Conversational Connect Developer Portal.

Enable the Templates and Connect Messaging API capabilities on the application. These are both required for the connector integration.

Figure 2. Enabling the Templates and Connect Messaging API capabilities on the new application.

Open the details of the created application and note the Client ID and Client Secret. These will be entered into the connector at deployment time.

Figure 3. Application details showing the application ID.

Figure 4. Application Client ID and Client Secret.

Step 2: Retrieve the Webhook Signature Secret

In the Conversational Connect Developer Portal, navigate to Settings > Signed Webhooks. Note the signature secret. The connector will use this value to verify the authenticity of webhook payloads received from Conversational Connect.

Figure 5. Webhook signature secret in the Conversational Connect Developer Portal.

Step 3: Deploy the Connector Instance on Vonage Cloud Runtime

In the Vonage Cloud Runtime Marketplace, find the "Vonage Conversations for MoEngage" application and click "Deploy new instance".

Figure 6. Deploying a new instance from the VCR Marketplace.

Select the region, enter your API secret, and choose a name for your application. Note: the webhook URL derived from this deployment (https://neru-<api-key>-<product-name>-<application-name>.euw1.runtime.vonage.cloud/webhooks/cc) must be at most 100 characters, so the application name should be no longer than 8 characters.

Region alignment note: Conversational Connect is hosted in Europe (Frankfurt) and US (Central) only. Match your Cloud Runtime region to your Conversational Connect region to keep data in the same region.

Figure 7. Region, API secret, and application name.

Select the Conversational Connect configuration type.

Figure 8. Selecting the Conversational Connect configuration type.

Enter the Client ID, Client Secret, and Webhook Signature secret noted from the previous steps.

Figure 9. Conversational Connect credentials and webhook signature.

Select the channel(s) you want to enable on this connector instance.

Figure 10. Selecting the channels for this instance.

WhatsApp channel configuration

Enter the WhatsApp Business number that will be used to send messages. This must match a number configured in your Conversational Connect account. Optionally, customise the auto-reply messages sent to end consumers for opt-in and opt-out actions.

Figure 11. WhatsApp channel configuration, business number.

Figure 12. WhatsApp channel configuration, custom auto-reply messages.

Step 4: Wait for Instance Provisioning

Figure 13. Instance provisioning in progress.

Step 5: Launch the Connector Application

Once the instance is provisioned, launch the application.

Figure 14. Launching the connector application.

Step 6: Log in to the Admin Panel

Log in to the connector admin panel using the Vonage account that owns the API Key on which the instance is deployed.

Figure 15. Admin panel log-in.

Step 7: Note the Conversational Connect Webhook URL

In the admin panel, note the Conversational Connect Webhook URL. It has the form: <instance-url>/webhooks/cc. This is the URL that Conversational Connect will call to notify the connector of inbound events and delivery status.

Figure 16. Conversational Connect Webhook URL in the admin panel.

Step 8: Configure the Webhook in Conversational Connect

In the Conversational Connect Developer Portal, navigate to Settings and click "+ Add Webhook".

Figure 17. Add Webhook in the Conversational Connect Developer Portal.

Enter the webhook URL from the admin panel (Step 7) and select both message:dlr_status and message:inbound scopes. Save the webhook. Conversational Connect will verify that the endpoint is reachable and mark it as active.

Figure 18. Entering the webhook URL and selecting the required scopes.

Step 9: Generate a Bearer Token for Authentication

In the admin panel, navigate to the Tokens tab and click "Generate token".

Figure 19. Generate token action in the admin panel.

Set the token expiry. Available options include 24 hours, 7 days, 30 days, 90 days, or "never".

Figure 20. Token expiry selection.

Important: The full token is displayed only once, at the time of generation. Copy and store it securely. After generation, only a masked preview is shown. If the token is lost, revoke it and generate a new one.

Figure 21. Generated token, displayed once.

Step 10: Configure the Sender Profile in MoEngage

In the MoEngage dashboard, navigate to:

Settings > Channels > WhatsApp > Vonage Connector

Click "+ Sender" to create a new sender configuration.

Figure 22. Create WhatsApp sender in MoEngage.

Enter the Authorization value as Bearer <token>, using the token generated in Step 9.

Figure 23. Bearer token entered in the MoEngage sender configuration.

For the API URL and Template Sync URL fields, use the values displayed in the connector admin panel. The admin panel provides these values ready to copy and paste.

Figure 24. API URL and Template Sync URL shown in the connector admin panel.

Figure 25. API URL and Template Sync URL entered in MoEngage.

After saving the initial sender configuration, MoEngage displays the Enable Delivery Tracking URL. Copy this URL.

Figure 26. Enable Delivery Tracking URL displayed by MoEngage.

Return to the connector admin panel and paste the Delivery Tracking URL into the corresponding field. This tells the connector where to POST delivery events and inbound reply events for MoEngage to receive.

Figure 27. Delivery Tracking URL entered in the connector admin panel.

4. Configure the WhatsApp Channel, Standalone Mode

Standalone mode is functionally equivalent to v1.0: WhatsApp campaigns are delivered directly through the Vonage Messages API without a Conversational Connect dependency. Compared to v1.0, the primary differences are:

• The authentication method is now a bearer token generated on the connector's admin panel, replacing the Custom / Basic Auth API-key header used in v1.0.
• Delivery URLs are now configured through the connector admin panel instead of at deploy time in the VCR form.

Because of these changes, some setup steps are reordered compared to v1.0.

Step 1: Deploy the Connector Instance on Vonage Cloud Runtime

In the Vonage Cloud Runtime Marketplace, find the "Vonage Conversations for MoEngage" application and click "Deploy new instance". Select the region, enter your API Key, and choose a name for your application.

Figure 28. Region, API key, and application name.

Select the Standalone configuration.

Figure 29. Selecting the Standalone configuration.

Webhook Signature: Enter the signature secret from your Vonage Dashboard > Settings > Signed Webhooks page. The connector uses this to verify Messages API delivery callbacks.

Figure 30. Webhook signature entry.

Figure 31. Standalone deployment form, full view.

WhatsApp channel configuration

Link the WhatsApp Business number to the application.

Figure 32. Linking a WhatsApp number to the application.

Figure 33. WhatsApp number selection.

Enter the number into the connector configuration.

Figure 34. WhatsApp number entered in the configuration.

Steps 2-5: Provisioning, Launch, Admin Panel Log-in

These steps are identical to the Conversational Connect mode flow. Wait for the instance to provision, launch the application, and log in to the admin panel using your Vonage account.

Figure 35. Instance provisioning.

Figure 36. Launch the application.

Figure 37. Admin panel log-in.

Step 6: Generate a Bearer Token and Configure MoEngage

Generate a bearer token as described in Section 3, Step 9. Then configure the MoEngage WhatsApp sender profile using the Bearer <token> Authorization value, the API URL and Template Sync URL shown in the connector admin panel, and the Delivery Tracking URL that MoEngage returns. See Section 3, Step 10 for the detailed sender configuration steps; the flow is identical in Standalone mode.

5. Post-Setup Steps (Both Modes)

From this point on, the flow for syncing templates, personalization, and launching a campaign is the same as in v1.0 and applies to both operating modes.

5.1 Sync WhatsApp Templates

Template alignment between the source (Vonage / Meta in Standalone mode, or Conversational Connect in Conversational Connect mode) and MoEngage is critical. WhatsApp Business Messaging requires that all outbound business-initiated messages use a pre-approved template. Approved templates can be synced automatically into MoEngage, so manual recreation is not required in most cases.

5.1a. Sync Templates in MoEngage (recommended)

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 using the Template Sync URL configured in Step 10 (or Section 4 Step 6) and add them to the list.

Figure 38. MoEngage Approved templates view with the "Sync Template" action.

5.1b. Add Template Manually (fallback)

If a template was not picked up by sync, add it manually via "+ Template" in the Approved templates section. Enter the exact template name as approved on the source side (Vonage / Meta or Conversational Connect), select the Vonage Connector service provider, select the sender profile you configured, and match the language and category.

Figure 39. Add template form, Settings section.

Match the content structure exactly. Placeholder count and order must remain consistent with the approved template, otherwise campaign sends will fail with a "1022, Invalid template or template parameters" error.

Figure 40. Template Content section, Header / Body / Footer / Buttons.

Note on carousel templates in Conversational Connect mode

Conversational Connect does not currently support dynamic parameters on carousel cards. Carousel templates will sync from Conversational Connect to MoEngage, but MoEngage assumes dynamic media by default, which causes a mismatch. After sync, either:

• Edit each synced carousel template in MoEngage and change the card media from dynamic to static, matching the media on the Conversational Connect template.

Figure 41. Editing a synced carousel template to change card media to static.

• Or remove the synced carousel from MoEngage and manually recreate it as a static carousel.

Dynamic carousel support on the Conversational Connect side is planned for a near-term release, after which this workaround will not be required.

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

5.2a. 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.

Figure 42. Campaign Content step, Select sender and template.

5.2b. 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 43. Placeholder personalization, typing @ opens the personalization picker.

5.2c. Select the Attribute to Inject

In the WhatsApp Personalization dialog, search for and select the user attribute that should populate the placeholder. The selected attribute will resolve dynamically at send time for each user in the audience.

Figure 44. WhatsApp Personalization dialog with attribute search.

5.2d. Set Fallback Behaviour

For each personalized placeholder, define what should happen if the attribute value is missing. 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 45. Fallback options with "Replace text" selected.

5.3 Build and Launch a Campaign

5.3a. Create a New WhatsApp Campaign

In the MoEngage dashboard, navigate to Campaigns > WhatsApp (One-time) > Create.

5.3b. Configure Target Users

In the Target users step, configure the campaign name, tags, audience selection, exclusions, and opt-in handling. Leave "Send campaign to users ignoring Opt-in preference" unchecked to respect each user's opt-in status.

Figure 46. Campaign Target users step.

Test send tip: For end-to-end verification before going to a full audience, scope the audience filter to a single test user. This lets you confirm delivery before publishing to the full audience.

5.3c. Configure Content

In the Content step, select the sender and the approved template, then map placeholder inputs and fallbacks as described in Section 5.2. The right-hand preview pane shows a live preview of the message.

5.3d. Schedule and Publish

In the Schedule and goals step, configure the send schedule (immediate, scheduled, 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, which will dispatch them either through the Vonage Messages API (Standalone) or through Conversational Connect (CC mode).

5.3e. Monitor Delivery in Campaign Analytics

The connector translates delivery status callbacks into MoEngage's DLR format and posts them to the Delivery Tracking URL configured in the admin panel. Events flow into MoEngage's campaign analytics in near real time.

• 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 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").
• Reply events: Supported quick-reply and CTA button clicks are forwarded to MoEngage as reply events and appear under the campaign's engagement metrics, in both modes.
• Opt-out attribution: STOP and opt-out replies are synced back to the MoEngage contact record, automatically suppressing those users from subsequent campaign sends.

Figure 47. Campaign analytics view showing delivery and engagement metrics.

There is typically a few seconds of latency between message delivery and MoEngage analytics updates, depending on the carrier and, for WhatsApp, on Meta's status callback timing.

6. 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 the bearer token: Confirm the Authorization value in MoEngage sender configuration is set to Bearer <token> using a valid, non-revoked, non-expired token from the connector admin panel. If in doubt, generate a new token and update MoEngage.
• Verify the API URL and Template Sync URL: Confirm these match the values displayed in the connector admin panel.
• Verify the Delivery Tracking URL: Confirm the URL entered in the connector admin panel matches the URL displayed in MoEngage's sender configuration.
• Check opt-in status: Confirm the test recipient has not previously opted out.
• For Conversational Connect mode: Confirm the webhook in the Conversational Connect Developer Portal is active and points at the correct <instance-url>/webhooks/cc URL. Confirm the webhook signature secret matches on both sides.
• For Standalone mode: Confirm the Vonage Dashboard "Signed webhooks" signature secret matches the one entered at deploy time.

End-to-End Message Lifecycle

Every WhatsApp campaign send follows four stages. Each stage has its own log source. When troubleshooting, work through the stages in order.

Stage 1: MoEngage triggers the campaign send. Where to look: MoEngage Dashboard, Campaign Analytics. MoEngage posts a send request to the connector's API URL for each user in the audience.

Stage 2: Connector receives and dispatches. Where to look: Vonage Cloud Runtime, Instances, Your Instance, Logs. The connector receives the send request, authenticates it against the bearer token, validates the payload, and dispatches it either to the Vonage Messages API (Standalone) or to Conversational Connect (CC mode).

Stage 3: Downstream service delivers the message. Where to look: Vonage Customer Dashboard Message Logs (Standalone) or Conversational Connect Developer Portal (CC mode). Look for the outbound message record; a "delivered" status confirms the message reached the recipient.

Stage 4: DLR posted back to MoEngage. Where to look: connector logs and MoEngage Campaign Analytics. The connector translates the status callback into MoEngage's DLR format and posts it to the Delivery Tracking URL.

Status mapping

Figure 48. Connector logs showing a rejected message status callback.

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

Common error scenarios

7. How to Get Help

Best way (recommended): Vonage Help Center

https://api.support.vonage.com/hc/en-us/requests/new?ticket_form_id=27404957240092 

Select the form titled "Using Vonage Connector", then select your connector, then "Using Vonage Conversations for MoEngage".

What to include (for faster resolution)

8. For End Users, Campaign Delivery Experience

End users do not need to perform any configuration. Once the administrator has completed setup, 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.
• 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 receives a confirmation auto-reply, if configured, and is 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.
• In Conversational Connect mode, quick-reply buttons on templates can trigger bot flows, live agent handoff, or opt-in / opt-out actions configured on the Conversational Connect side. The user does not need to know which mode is in use; the behaviour they see depends on how the brand has configured the template.
• Quick-reply button clicks (including any URL-button taps) are forwarded to MoEngage as inbound events in both modes.
• Free-text replies that do not match an opt-in or opt-out keyword are discarded at the connector in Standalone mode; in Conversational Connect mode they are handled inside the brand's Conversational Connect chat flows or by a live agent.

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