MoEngage Connector - SMS Channel Guide

Table of Contents

1. Introduction

2. Prerequisites

3. Configure Vonage as a Custom SMS Connector

4. Message Variations: A/B Test and Locales

5. Campaign Configuration

6. Troubleshooting and Log Access

7. How to Get Help

8. For End Users, Campaign Delivery Experience

1. Introduction

Vonage is a Communications Platform as a Service (CPaaS) provider that enables consumers and businesses to connect and communicate on any device through cloud-hosted voice, video, chat, and SMS.

This guide walks you through configuring the Vonage MoEngage Connector for the SMS channel in version 2.0. Version 2.0 offers two operating modes: Standalone mode (SMS delivery through the Vonage Messages API, functionally equivalent to v1.0) and Conversational Connect mode (SMS delivery through Vonage Conversational Connect). You will set Vonage as a custom SMS service provider in MoEngage, deploy the connector instance on Vonage Cloud Runtime, and launch your first SMS campaign. For an overview of the connector, refer to the main Vonage Conversations for MoEngage knowledge base article.

2. Prerequisites

Before you begin, make sure you have the following:

• Access to your Vonage Dashboard (https://dashboard.nexmo.com/private/dashboard) to retrieve your API Key.
• Access to Vonage Cloud Runtime (https://developer.vonage.com/en/cloud-runtime) to deploy the connector instance.
• Access to Vonage Dashboard Settings (https://dashboard.vonage.com/settings) to obtain your Signature secret (Standalone mode only).
• Admin access to the MoEngage dashboard to configure SMS sender profiles and campaigns.

For Conversational Connect mode, additionally:

• A Conversational Connect account with the SMS channel already configured (SMS long virtual number linked to your Conversational Connect account).
• A Conversational Connect application with the Connect Messaging API capability enabled (see the WhatsApp channel guide, Section 3 Step 1, for the shared application creation flow).
• The webhook signature secret from the Conversational Connect Developer Portal.

Parameters you will need

Have the following parameters ready before starting the configuration:

3. Configure Vonage as a Custom SMS Connector

This section walks you through setting up Vonage as a custom SMS service provider on the MoEngage dashboard. The v2.0 configuration is a two-pass flow with an admin-panel step in between: you begin in MoEngage, switch to Vonage Cloud Runtime to deploy the connector instance, complete the connector admin panel configuration (bearer token and delivery URL), then return to MoEngage to complete the configuration.

Important: The order of operations matters. Follow the sequence below to avoid rework.

Step 1: Begin Sender Configuration in MoEngage

Log in to the MoEngage Dashboard and create the custom SMS sender:

1. Navigate to Settings > Channels > SMS & RCS > Sender Configuration.
2. Click "+ Add SMS Sender" at the top right.
3. Choose "Add custom service provider".

1a. Fill the Service Provider Details

Fill the first part of the form with the service provider details:

• Service provider name: A name to identify this configuration, for example "My Vonage Service Provider".
• Sender name: The display name for the sender, for example "Vonage Provider".
• Sender ID: Optional. The Sender ID that recipients will see as the source of the SMS, where supported by the destination carrier. Sender ID requirements and registration vary by country.
• Sender type: Select Promotional or Transactional based on your use case.
• Mark as default: Enable this toggle if you want this service provider to be picked as the default for all new SMS campaigns.

Figure 1. Add SMS Sender in MoEngage, custom service provider selection.

Figure 2. Service Provider details form.

1b. Fill the API Details (First Pass)

Continue to the second part of the form. Use the dummy URL https://dummy.euw1.runtime.vonage.cloud/ as the API URL for now; you will replace it with the actual connector instance URL in Step 3, after the connector is deployed.

Important: Use the exact domain and trailing slash. MoEngage generates the Delivery Tracking URL based on this domain, so the format must be correct.

Fill in the API details as follows:

• API URL: https://dummy.euw1.runtime.vonage.cloud/ (placeholder, to be replaced in Step 3).
• Method: POST
• Authorization header: Set the value to Bearer <token>. You will generate this token in the connector admin panel in Step 2c; for now you can save a placeholder such as Bearer PLACEHOLDER and update it after Step 2c.
• Content-Type header: application/json
• Body type: JSON
• Body key-value pairs: Add the standard MoEngage SMS keys: text mapped to Moesms_message, and to mapped to Moesms_destination.

Click Save to commit the first pass of the configuration. The sender is now created in MoEngage, but the setup is not yet complete.

Step 2: 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 3. Deploying a new instance from the VCR Marketplace.

Select the region, enter your API secret, and choose a name for your application. Then select the operating mode:

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

2a. Choose Operating Mode

Standalone mode. SMS is delivered directly through the Vonage Messages API. Enter the Webhook Signature secret from your Vonage Dashboard > Settings > Signed Webhooks page.

Figure 5. Selecting the Standalone configuration type.

Figure 6. Webhook signature entry (Standalone).

Conversational Connect mode. SMS is delivered through Vonage Conversational Connect. Enter the Client ID, Client Secret, and Webhook Signature secret from your Conversational Connect application (see the WhatsApp guide, Section 3 Steps 1-2 for the source of these values).

Figure 7. Selecting the Conversational Connect configuration type.

Figure 8. Conversational Connect credentials entered.

2b. SMS Channel Configuration

Select the SMS channel from the channels list.

Figure 9. Channel selection.

Standalone mode. Enter the Brand Name to be used as the sender identifier, or exclusively, link a Vonage long virtual number (LVN) to the application. Only one of the two can be entered.

Figure 10. SMS Brand Name entry (Standalone).

Figure 11. SMS LVN linking (Standalone).

Figure 12. Entering the LVN into the configuration.

Conversational Connect mode. Enter the LVN or Brand Name that matches a number configured in your Conversational Connect account. Only one of the two can be entered.

Figure 13. SMS channel configuration (Conversational Connect mode).

2c. Wait for Provisioning, Launch, and Generate a Bearer Token

Wait for the connector instance to be provisioned, then launch the application.

Figure 14. Instance provisioning.

Figure 15. Launch the application.

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

Figure 16. Admin panel log-in.

In the admin panel Tokens tab, click "Generate token" and set the expiry. The token is displayed only once; copy and store it securely.

Figure 17. Generate token in the admin panel.

Figure 18. Token expiry selection.

Figure 19. Generated token, displayed once.

2d. (Conversational Connect mode only) Configure the Webhook

In the admin panel, note the Conversational Connect Webhook URL (<instance-url>/webhooks/cc). In the Conversational Connect Developer Portal, add a webhook with this URL and select both message:dlr_status and message:inbound scopes. Conversational Connect will verify that the endpoint is reachable.

Step 3: Complete the Sender Configuration in MoEngage

Return to the MoEngage Dashboard to replace the dummy API URL with your actual connector Instance URL, update the Authorization header with the generated bearer token, and complete the field mapping configuration.

3a. Replace the API URL and Authorization Header

In MoEngage, navigate to Settings > Channels > SMS & RCS > Sender Configuration. Edit the sender you created in Step 1 and advance to the Sender Details step.

The connector admin panel displays the API URL you should use. Copy the value from the admin panel:

Figure 20. API URL displayed in the connector admin panel.

Paste it into the MoEngage sender configuration. Update the Authorization header value to Bearer <token> using the token generated in Step 2c.

Figure 21. Sender Details with the actual API URL and bearer token authorization.

3b. Confirm Body Key-Value Mappings

Confirm that the body key-value pairs use the standard MoEngage SMS keys:

• text mapped to Moesms_message
• to mapped to Moesms_destination

Figure 22. Body key-value pairs mapping.

Save and advance to the next page.

Figure 23. Save and continue to the next page.

3c. Retrieve the Incoming Messages and Delivery Callback URL

MoEngage now displays the Incoming Messages and Delivery callback URL that the connector should use to post delivery events and inbound messages. Copy this URL.

Figure 24. Incoming Messages and Delivery callback URL displayed by MoEngage.

Return to the connector admin panel and paste the URL into the corresponding SMS delivery URL field.

Figure 25. Delivery URL entered in the connector admin panel.

3d. Configure Delivery Response Field Mappings

Recommended approach: Click "Send test SMS" to send a test message. MoEngage uses the response from this test send to auto-populate the mapping fields, giving you a guided dropdown-style configuration that is less error-prone than manual setup. Retry if a timeout occurs (error 408).

Manual alternative: If a test send is not possible, choose "Map fields manually" and configure each mapping as free-text. This is supported but more error-prone, so the test-send approach is preferred when feasible.

When SMS sending is triggered, the connector returns a trackingId in the response, which MoEngage uses to link the delivery status back to the original message. Set the mappings as follows:

• Attribute storing unique ID of the sent response: trackingId
• Attribute storing Unique delivery ID field of delivery response: trackingId
• Attribute storing delivery status: status
• Success values for delivery status: delivered
• Attribute storing failure reason: error

Figure 26. Delivery response field mappings.

Click Save to commit the final configuration. The Vonage SMS sender is now fully configured and ready to be used in campaigns.

4. Message Variations: A/B Test and Locales

SMS message content for a campaign is composed directly in the campaign's Content step (covered in Section 5), not in a separate Templates area. There is no SMS-template object to create and re-use across campaigns, as you may be familiar with for WhatsApp.

For scenarios where you want to send variations of the same campaign to different users, MoEngage provides two built-in mechanisms that operate at the campaign level:

A/B Test

A/B Test automatically creates and distributes multiple message variations across your audience to optimize for engagement.

1. In the campaign's Content step, click "+ A/B test" in the top right.
2. Add one or more additional message variations. Each variation has its own message body, with personalization placeholders configured independently.
3. Configure the distribution percentage for each variation, or let MoEngage auto-distribute evenly.
4. Optionally configure a goal metric (delivered, clicked, or a conversion event) so MoEngage can identify the winning variation.

Figure 27. Campaign Content step with A/B test action.

Locales

Locales lets you send different message content based on the user's locale attribute (typically language and region, for example en-US, fr-FR, es-MX).

1. In the campaign's Content step, click "+ Locale" in the top right.
2. Select the locale you want to add (for example, Spanish).
3. Enter the localized message body for that locale, including any personalization placeholders.
4. Repeat for each locale you want to support. The default message (configured at the top of the Content step) is sent to any user whose locale does not match a configured variation.

Note: A/B Test and Locales can be used together. For example, you can run an A/B Test within each locale, where MoEngage distributes the locale's variations independently across the audience speaking that language.

5. Campaign Configuration

Once the sender is configured, you can create and launch SMS campaigns from MoEngage's campaign builder. The flow mirrors the standard MoEngage campaign creation experience, with the Vonage sender selected as the SMS service provider.

5a. Create a New SMS Campaign

From the MoEngage dashboard, click "+ Create" (or the New Campaign action). In the campaign type picker, expand the SMS section and select "One Time" (single immediate or scheduled send), "Periodic" (recurring), or "Event Triggered" (triggered by user events).

Figure 29. New Campaign picker with SMS options.

5b. Configure Target Users

In the Target users step, configure the campaign name, mobile number attribute, tags, audience selection, and exclusions.

• Campaign name: A descriptive name for the campaign.
• User attribute that stores user's mobile number: Select the attribute that holds each user's mobile number, typically "Mobile Number (Standard)".
• 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.

Test send tip: Scope the audience filter to a single test user for end-to-end verification before publishing to the full audience.

Figure 30. SMS campaign Target users step.

5c. Configure Content

In the Content step:

• SMS sender: Select your Vonage sender from the dropdown (it will display with the "(CUSTOM)" suffix).
• Template ID: Optional. If the destination carrier or local regulation requires a pre-registered Template ID for the message body, enter it here.
• Message: Enter the SMS body text. Use personalization placeholders such as {{UserAttribute['Name']}} to insert dynamic user attribute values. The right-hand preview pane displays the message as it will appear on a mobile device.
• Shorten and track URLs: Optional. MoEngage can automatically shorten and track URLs included in the SMS body.

Figure 31. SMS campaign Content step.

5d. Schedule and Publish

In the Schedule and goals step, configure the send schedule, set any conversion goals or A/B test variants, and review the campaign summary. Click "Publish" to launch. MoEngage will begin posting send requests to the connector, which dispatches them either through the Vonage Messages API (Standalone) or through Conversational Connect (CC mode).

5e. Monitor Delivery in Campaign Analytics

The connector forwards delivery status callbacks to MoEngage's Delivery Tracking URL. These events flow into MoEngage's campaign analytics in near real time. In the campaign's Analytics tab, you will see metrics for:

• Attempted: Total number of send attempts.
• Sent: Messages successfully accepted by the connector and dispatched downstream, with a Sent rate percentage.
• Failed To Send: Messages that could not be sent, with a Failure rate percentage.
• Delivered: Messages confirmed as delivered to the recipient, with a Delivery rate percentage.
• Clicked: If URL shortening was enabled, the number of users who clicked a link in the SMS, with a CTR percentage.

Figure 32. SMS campaign analytics with Delivery and Engagement metrics.

6. Troubleshooting and Log Access

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

Initial checks

• Verify the API URL: Confirm the API URL in MoEngage's sender configuration is your actual connector Instance URL, with the trailing slash, not the dummy URL from the first pass.
• Verify the bearer token: Confirm the Authorization header value is in the exact format "Bearer <token>", using a token that has been generated in the connector admin panel and is not expired or revoked.
• Verify the Delivery Tracking URL: Confirm the SMS Delivery URL configured in the connector admin panel matches the URL displayed in MoEngage's Delivery Tracking screen.
• Verify the Signature secret (Standalone mode): Confirm the Signature secret entered during connector deployment matches the value in your Vonage Dashboard Settings, Signed Webhooks section.
• Verify the field mappings: Confirm the trackingId, status, delivered, and error mappings in the Delivery Tracking configuration are set correctly.
• Check opt-in status: Confirm that the test recipient has not previously opted out. Users who have replied STOP are suppressed from future sends.
• For Conversational Connect mode: Confirm the webhook in the Conversational Connect Developer Portal is active and points at the connector's <instance-url>/webhooks/cc URL. Confirm the webhook signature secret matches.

End-to-End Message Lifecycle

Every SMS campaign send follows four stages. Each stage has its own log source. 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. MoEngage's orchestrator 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 against the bearer token, validates the payload, and dispatches it through the selected mode.

Key log lines to look for:

• POST /webhooks/message-dispatcher, confirming the connector received the request from MoEngage.
• Sending POST to .../queue/.../enqueue, confirming the message was queued.
• Sending SMS via Vonage: msg_id=..., confirming the message was dispatched 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).

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

Status mapping

For failed or rejected messages, the connector includes the provider error code and description in the MoEngage delivery payload, so the failure reason surfaces in MoEngage analytics.

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)

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

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 SMS campaign delivery transparently. From the end user's perspective:

• The user receives an SMS from the brand's configured Sender ID or LVN. The message may include personalization, such as the user's name, account details, or other dynamic content.
• 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 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.
• If the SMS includes a shortened tracked URL and the user clicks it, the click event is captured and surfaced in MoEngage's campaign analytics under the Clicked metric.

The Vonage MoEngage Connector operates entirely behind the scenes. End users interact only with the brand's SMS communication in their standard messaging app, and any reply they send is processed by the connector and reflected in MoEngage's contact records.