MoEngage Connector - SMS Channel Guide

Table of Contents

1. Introduction

2. Prerequisites

3. Configure Vonage as a Custom SMS Connector

        Step 1: Begin Sender Configuration in MoEngage

        Step 2: Retrieve the Delivery Tracking URL

        Step 3: Deploy the Connector on Vonage Cloud Runtime

        Step 4: Complete the Sender Configuration in MoEngage

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. 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 MoEngage Connector itself, including architecture, key benefits, and the WhatsApp channel setup, refer to the main Vonage MoEngage Connector knowledge base article.

2. Prerequisites

Before you begin, make sure you have the following:

• Access to your Vonage Dashboard to retrieve your API Key and API Secret.
• Access to Vonage Code Hub to deploy the connector instance.
• Access to Vonage Dashboard Settings to obtain your Signature secret.
• Admin access to the MoEngage dashboard to configure SMS sender profiles and campaigns.

For details on the underlying Vonage SMS API, see the Vonage SMS API reference.

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 configuration is a two-pass flow: you begin in MoEngage, switch to Vonage Cloud Runtime to deploy the connector instance, then return to MoEngage to complete the configuration.

Important: The order of operations matters. You will need to retrieve the MoEngage Delivery Tracking URL from the partially-saved sender configuration before deploying the connector, because the URL is required as a parameter during deployment.

Step 1: Begin Sender Configuration in MoEngage

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

1. Navigate to Settings > Channel > SMS & RCS > Sender Configuration.
2. Click "+ Add SMS Sender" at the top right of the screen.
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. MoEngage Add Custom Connector sender, Service Provider step with general details and sender name.

1b. Fill the API Details (First Pass)

Continue to the second part of the form (API details). For now, use the dummy URL https://dummy.euw1.runtime.vonage.cloud/ as the API URL. You will replace this with the actual connector Instance URL once the connector has been deployed in Step 3.

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 remaining API details as follows:

• API URL: https://dummy.euw1.runtime.vonage.cloud/ (placeholder, to be replaced in Step 4).
• Method: POST
• Authorization header: Set the value to Custom <apikey>:<apisecret>, where you replace <apikey> and <apisecret> with your Vonage API Key and API Secret, joined by a colon.
• 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.

Figure 2. Sender Details step with the dummy API URL, Authorization header, and Moesms key-value mappings.

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: Retrieve the Delivery Tracking URL

MoEngage generates the Delivery Tracking URL after the sender is saved. You need to retrieve this URL before deploying the connector, because the connector requires it as a parameter during deployment.

1. Navigate back to Settings > Channel > SMS & RCS > Sender Configuration.
2. Locate your newly created sender card. Click the dots menu (vertical ellipsis) on the card and select "Edit".
3. Click "Next" through the wizard until you reach the Delivery Tracking page.
4. Copy the Incoming Messages and Delivery Callback URL shown on this page. This is the MoEngage Delivery Tracking URL that the connector will post status events to.

Figure 3. Edit Custom Connector sender wizard, Delivery Tracking page with the URL copied to clipboard.

Cancel the edit (do not save changes at this point) and return to the Sender Configuration screen. You now have the Delivery Tracking URL ready to use in the next step.

Step 3: Deploy the Connector on Vonage Cloud Runtime

With the Delivery Tracking URL in hand, deploy a new connector application instance on Vonage Code Hub. Select the MoEngage Connector application and proceed to the project deployment form.

3a. Configure the Deployment Parameters

In the project deployment form, fill the parameters as follows:

• SMS MoEngage Delivery Tracking URL: Paste the URL you copied in Step 2. This is the URL the connector will use to send SMS delivery events (SUCCESS / FAILURE) back to MoEngage.
• Delivery event Signature secret (internal): Your Vonage Signature secret. You can find this on the Vonage Dashboard Settings page, under the "Signed Webhooks" section.

Figure 4. Project deployment dialog with the SMS MoEngage Delivery Tracking URL field highlighted.

3b. Locate the Signature Secret

If you have not already retrieved your Signature secret, navigate to the Vonage Dashboard Settings page. Scroll to the "Signed Webhooks" section and copy the Signature secret value. The Signature method should be SHA-256 HMAC, which is the only algorithm supported by the Messages API.

Figure 5. Vonage Dashboard Signed Webhooks section, Signature secret and SHA-256 HMAC method.

3c. Deploy and Retrieve the Instance URL

Complete the deployment. Once the deployment is successful, the Vonage Code Hub will display the Instance overview, which includes the Instance URL. Copy the Instance URL, you will need it in the next step.

Figure 6. Vonage Code Hub Instance overview showing the deployed Instance URL.

Step 4: Complete the Sender Configuration in MoEngage

Return to the MoEngage Dashboard to replace the dummy API URL with your actual connector Instance URL and complete the field mapping configuration.

4a. Replace the API URL

In MoEngage, navigate to Settings > Channel > SMS & RCS > Sender Configuration. Edit the sender you created in Step 1, advance to the Sender Details step, and replace the dummy API URL with your actual connector Instance URL.

Important: Include the trailing slash when pasting the Instance URL, for example https://neru-7eabaf11-vonage-moengage-for-ivan-jun1ee.euw1.runtime.vonage.cloud/. MoEngage requires the exact domain with a trailing slash for the request routing to work.

Figure 7. Sender Details with the actual connector Instance URL pasted into the API URL field.

4b. Configure Delivery Response Mapping

Click "Next" to advance to the Delivery Tracking configuration screen. This is where you tell MoEngage how to interpret the response payloads from the connector.

Recommended approach: Click "Send test SMS" to send a test message. MoEngage will use 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, you can 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.

Verify before saving: Ensure the tracking URL displayed here exactly matches the URL you used during connector deployment in Step 3a. A mismatch will result in delivery events not being received by MoEngage.

4c. Set the Field Mappings

Configure the attribute mappings so MoEngage can correlate the connector's responses with the messages sent. When SMS sending is triggered, Vonage 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 8. Delivery Tracking mapping screen with sent / delivery response payloads and the 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. Use this when you want to compare different copy, calls to action, or personalization strategies and let MoEngage measure which performs best.

To add A/B Test variations in an SMS campaign:

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 9. Campaign Content step with the "+ A/B test" action and multiple message variations

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). Use this when you have a multilingual audience and want each user to receive the message in their preferred language, without running separate campaigns per language.

To add Locale variations in an SMS campaign:

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.

Figure 10. Campaign Content step with the "+ Locale" action and multiple locale-specific message bodies.

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 the "+ Create" button (or the New Campaign action). In the campaign type picker, expand the SMS section and select "One Time" (for a single immediate or scheduled send), "Periodic" (for recurring sends), or "Event Triggered" (for sends triggered by user events).

Figure 11. New Campaign picker with SMS expanded, showing One Time, Periodic, and Event Triggered options.

5b. Configure Target Users

In the Target users step, configure:

• 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 (user property, user behavior, user affinity, or custom segment).
• Exclude Users: Optionally exclude segments from the campaign.

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.

Figure 12. SMS campaign Target users step with mobile number attribute and audience filters.

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

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 13. SMS campaign Content step with Vonage sender selected, message body with personalization, and live preview.

5d. Schedule and Publish

In the Schedule and goals step, configure the send schedule (immediate, scheduled for a future date and time, or recurring for Periodic campaigns), 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 for SMS delivery.

5e. Monitor Delivery in Campaign Analytics

Once the campaign is live, the connector forwards Vonage delivery status callbacks (success, failure) 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 to Vonage, 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.

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 Authorization header: Confirm the Authorization header value is in the exact format Custom <apikey>:<apisecret>, with your Vonage API Key and Secret joined by a colon.
• Verify the Delivery Tracking URL: Confirm the SMS MoEngage Delivery Tracking URL configured during connector deployment matches the URL displayed in MoEngage's Delivery Tracking screen.
• Verify the Signature secret: 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.

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

Every SMS 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 API URL 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.
• 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.

Stage 3: Vonage Messages API Delivers the Message

Where to look: Vonage Customer Dashboard, Message Logs

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

What to check:

• Message status: Look for the outbound message record. A "delivered" status confirms the message reached the recipient. A "submitted" status means the message was accepted by Vonage but not yet delivered.
• Carrier rejection: A "rejected" or "failed" status indicates the message was rejected by Vonage or the destination carrier. Common causes include an invalid recipient number, an unregistered or non-compliant Sender ID, missing carrier-required Template ID where applicable, or content filtering by the carrier.
• Error codes: If the message was rejected, note the provider error code and reference the Vonage Messages API error documentation for details.

Stage 4: Delivery Status 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 expected SMS delivery format and posted to the MoEngage Delivery Tracking URL. The status mapping is:

For failed or rejected messages, the connector includes the Vonage 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” and then select your connector -> “Using Vonage Conversations for MoEngage" 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, 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 the setup in Section 3, 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. 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 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.
• 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.