mPulse functional guide
This page provides information about the capabilities of mPulse within Redpoint Interaction (RPI), how sending messages/synchronizing state data works, and links to other resources.
Key capabilities
The mPulse SMS connector providers the following key capabilities:
Channel Configuration
The ability to send SMS messages via an Interaction using an Offer Activity and/or Queue Listener
Receiving state/disposition data via the Channel Synchronization Task
Using state/disposition data as inputs to additional workflows and downstream activities
Unique features
Compared to the other SMS connectors that RPI supports, the mPulse connector supports the following features:
Processing of state/disposition data via their webhook functionality
Ideal platform to use for Queue Listeners, as they support timely delivery of SMS messages
Various channel configuration options to optimize performance for outbound and inbound processing
Process flow
The following flow chart shows how the mPulse channel works within both outbound fulfillment and inbound state synchronization.
Outbound processing
Inbound processing
Outbound fulfillment
The mPulse connector performs the following steps when it is used as part of an outbound Offer Activity:
Step # | Step Description | APIs / SQL |
---|---|---|
1 | Initiate a connectivity test to validate the mPulse service is accessible. The connectivity test will fail if the response code does not return a 200. | Method: Endpoint: Headers:
Request Body:
JSON
Response Body (Example):
JSON
|
2 | If the connectivity fails, it will retry up to 10 attempts with an interval of every 1 minute. | N/A |
3 | If the channel is configured to auto-suppress unsubscribes, RPI will query the suppression SMS table to identify and suppress any matching phone numbers before generating batch for member records. | N/A |
4 | Render personalized content for each member using the Razor template. Each personalized content is written to specific member list batch and event upload batch. The number of records of a batch varies depending on the values configured in Max. list upload batch size and Max. event upload batch size channel configuration settings. | N/A |
5 | Member records are uploaded into mPulse in batch. If Enable asynchronous list upload is set to Phone Number Formatting: Phone numbers must be sanitized manually before utilizing them in any RPI SMS campaign executions using mPulse connector. The phone number must be in the following format:
e.g., Country Code must not be preceded by If the | Method: Endpoint: Headers (Asynchronous Member List Upload):
Request Body (example):
JSON
Response Body (Example):
JSON
Headers (Synchronous Member List Upload):
Request Body (example):
JSON
Response Body (Example):
JSON
|
6 | One or more member SMS event batches are sent into the default queue provider using the queue path value configured in Event upload content queue path channel setting. For each execution, a new queue path is created from the default queue provider if it is does not exist yet. The created queue path has the following format: Regardless of whether the Enable asynchronous event upload option is configured or not, SMS event batch will always be sent to the queue. If Enable asynchronous event upload is set | N/A |
7 | After uploading the specific member list batch asynchronously, mPulse service will be returning the result of the import job. The import job contains a | N/A |
8 | If member list batch uploaded asynchronously, RPI will be creating a database table called | SQL Query (Example):
SQL
|
9 | Once all member list batches have been uploaded asynchronously, RPI will be monitoring the import jobs recorded in The monitoring will continue every 5 seconds until it reaches the waiting time configured in Member list import timeout channel setting. During monitoring of the import jobs, only single main database connection is open for every database query being executed. | N/A |
10 | The import job status for each member list batch is sourced out from the database table called | SQL Query (Example):
SQL
|
11 | If there is no import status yet available for specific member list, and the waiting time has expired, the monitoring for import jobs will be terminated, and the Interaction workflow activity execution is set to failed state with the appropriate log messages. | N/A |
12 | All SMS event batches were stored in the queue path of the default queue provider will be fetched in preparation for sending these payloads into mPulse provider. The process of sending these payloads done concurrently based on the value configured in Max. send threshold. The sending process will continue until there are no payloads available in the queue. In the event of error however, a new queue path will be created with name in the following format: | Method: Endpoint: Headers (Asynchronous SMS event upload):
Request Body (example):
CODE
Response Body (example):
JSON
|
13 | Every successful SMS event batch being sent to mPulse provider is monitored by checking the upload status using the value of | Method: Endpoint: Headers:
Response Body (example):
JSON
|
14 | If the upload status is complete for specific SMS event batch, mPulse campaign is triggered per the event configured. Otherwise, it will wait for 60 seconds before the | N/A |
15 | If SMS event batches are successfully sent, the created queue path for specific execution will be cleanup. The Interaction log is updated with the total number of batches that were sent and failed. | N/A |
The Enable asynchronous list upload and Enable asynchronous event upload channel settings do not apply in the context of Queue Listener executions. Members and SMS Events are directly sent to mPulse without performing any extra monitoring on each API request.
The following are the database tables created during the outbound execution:
Table Name | Description |
---|---|
| Contains details such as Job ID of the member list batch uploaded asynchronously. |
| Contains details of SMS event batch uploaded. |
State data synchronization
Inbound process
Step # | Step Description | APIs / SQL |
---|---|---|
1 | mPulse SMS provider will be sending events via Redpoint Interaction callback service. Typically, mPulse will invoke the callback service URL configured. The URL is in the following format:
The | N/A |
2 | The Callback service processor system task reads and process the events available in the queue configured in | N/A |
3 | If client's main data warehouse is running either Snowflake DB or AWS Redshift DB, the recommendation is to utilize S3 bucket to bulk-load the records from S3 to temp table on the database. | N/A |
4 | To enable bulk-load using S3 bucket, enable the following RPI system configuration options: | N/A |
5 | When the Callback service processor system task process the events from the queue, each mPulse event is identified as | Example of MO (Mobile Originated):
JSON
Example of SUB (Subscribe):
JSON
Example of UNSUB (Unsubscribe):
JSON
Example of BULKUPSERT (Member List Upload Asynchronous Results):
CODE
|
6 | If the response type is If the response type is Finally, if the response type is | N/A |
7 | The mPulse channel synchronization system task process all state data from | SQL Query (Example):
SQL
|
The following are the database tables created during the inbound processing:
Table Name | Description |
---|---|
| Contains |
| Contains the Member list import details such as the Job ID. Each Job ID corresponds to specific member list batch uploaded asynchronously. Records are source out from the callback service |
| Contains the Member list import details that were imported successfully. Records are source out from the callback service |
| Contains the Member list import details that were failed during mPulse import process. Records are source out from the callback service |
RPI channel configuration
The following channel-specific fields are shown for the mPulse SMS channel:
Configuration Field | Details |
---|---|
API Service URL | Mandatory text property represents the API service URL used to connect to the mPulse service. It defaults to the value |
Username | Mandatory text property allows you specify a username to be used to connect to the mPulse service. It accepts a maximum of 100 characters. |
Password | Mandatory password-masked text field allows you specify a password to accompany the supplied username. It accepts a maximum of 100 characters. |
Account Id | Mandatory text property represents the account ID that will be used to connect to the mPulse service. This value can be found in the portal or provided by mPulse. It accepts a maximum of 100 characters. |
Audience list Id | Combo-box field represents an Audience list ID in the context of which all uploaded contacts will be grouped together. Specification of an audience list ID is mandatory. It is accompanied by an Add button, which allows you to specify one or more audience list IDs. Each can be a maximum of 100 characters in length. Refer to Step 2 in Section 2 of the "mPulse Configuration" section for information on identifying this value. |
Event name | Mandatory text property represents the event name that will be used to send mPulse SMS messages. It accepts a maximum of 100 characters. Refer to Step 2 in Section 3 of the "mPulse Configuration" section for information, which should reflect the same configured name. |
Content attribute name | Mandatory text property represents the custom attribute name that will be used to render SMS content for each subscriber. It accepts a maximum of 50 characters. Refer to Step 3 in Section 3 of the "mPulse Configuration" section for information, which should reflect the same configured name. |
Mobile phone | Mandatory text property represents the phone number that will be used to test connectivity of the mPulse service. It accepts a maximum of 100 characters. Any valid phone number can be used within this property. |
Max. list upload batch size | Numeric property represents the maximum number of recipients sent at a time to mPulse. It defaults to 50 and accepts a range of values from 1 to 2000. |
Max. event upload batch size | Numeric property represents the maximum number of SMS events sent at a time to mPulse. It defaults to 2000 and accepts a range of values from 1 to 2000. Lowering this value will result in longer campaign execution times. |
Enable asynchronous list upload | If this option is set, member list batch will be uploaded asynchronously. For larger send, it is recommended to set this option. |
Enable asynchronous event upload | If this option is set, SMS event batch will be uploaded asynchronously. For larger send, it is recommended to set this option. |
Max send threshold | Numeric property represents the maximum number of concurrent send operations that can be executed for a batch of email campaigns. It defaults to 10 and accepts a range of values from 1 to 10. |
Callback Service URL | The public-facing URL that mPulse will use to post the response and subscription events. |
Event upload content queue path | Mandatory text property allows you to configure a queue path of the default queue provider where SMS event batches are sent before they will be sending to mPulse. It accepts a maximum of 1000 characters. |
Member list import timeout | Numeric property represents the total waiting time (in minutes) of the member list import to complete. It defaults to 10 and accepts a range of values from 60 to 99999. |
Callback service installation configuration
Installation
To install the RPI mPulse Web API Callback Service:
Copy the entire
Deployment Files\Plugins Services\mPulseCallbackServiceWebAPI
folder into the root of the IIS web site where the mPulse Web API callback service will be hosted.In the
App_Config
folder, copy theConnectionStrings.Example.config
file and paste it in the same location. Rename the file toConnectionStrings.config
.In the
ConnectionStrings.config
file, modify the two entries within the<connectionString>
tags to point to the database server where the core RPI operational database is housed by replacing thelocalhost
string in the entries below with the name of the operational database server. If the RPI operational database is on the same machine as the RPI application server, then this does not need to be changed:
<add name="LoggingDatabase"
connectionString="Data Source=.;Initial Catalog=Pulse_Logging;Integrated Security=True;Connect Timeout=90;ConnectRetryCount=12;ConnectRetryInterval=10"
providerName="System.Data.SqlClient" />
<add name="OperationalDatabase"
connectionString="Data Source=.;Initial Catalog=Pulse;Integrated Security=True;Connect Timeout=90;ConnectRetryCount=12;ConnectRetryInterval=10"
providerName="System.Data.SqlClient" />
In IIS Manager:
Expand the website you created for the mPulse callback service.
Right-click on the
mPulseCallbackServiceWebAPI
folder and choose Convert to Application.Set the Application Pool to the same application pool that RPI runs under (
RPIAppPool
) or, if hosted on a different server, make sure the application pool runs under a security context that has access to the RPI Operational database referenced in the step above.You can test that your service is running correctly by right-clicking on the
mPulseCallbackServiceWebAPI
application in IIS and choosing Browse. If the service is running, you will see NuGet Dependencies content.
Important:
Once the callback service has been configured, submit a request into mPulse support and ask them to configure the callback URL with the following callback types:
Asynchronous Callback (this is used for the member upload)
SMS Subscription (these capture members that are new to the list ID configured in the channel)
SMS Unsubscription (these capture members who opt-out)
Mobile Originated (MO) callback (these capture the responses)
The callback URL is formatted as follows:
http://<FQDM or IP>:<port (optional)>/PostEvents/<rpi_client_id>
Ports:
When using Azure Service Bus as the queue, configure the firewall rule to allow outbound traffic to ports 443
, 5671
, and 5672
.
Upgrade
To upgrade the mPulse callback service at an existing RPI installation, please follow these steps:
Back up the mPulse Web API callback service
App_Config\ConnectionStrings.config
file andappsettings.json
file.Stop the mPulse Web API callback service in IIS Manager.
Copy the contents of
DeploymentFiles\Plugin Services\mPulseCallbackServiceWebAPI
into the mPulse Web API callback service website’s root folder.Start the
mPulseCallbackServiceWebAPI
application from IIS manager.
mPulse configuration
The following section provides the pre-requisite steps for configuring mPulse to work with RPI.
1: Log into mPulse portal
Step # | Description |
---|---|
1 | In a web browser, navigate to https://auth.mpulsemobile.com/ and click Communication Console. |
2 | Specify a username and password and click NEXT. |
2: Create audience
Step # | Description |
---|---|
1 | Navigate to Audience > Lists and click the Create a List button: |
2 | Enter a name and description for the List and click the Enable SMS channel option, which will expose additional options:
Once the List has been created, note the LIST ID associated with this list, as that will be used in the configuration of the channel in RPI, which is found in the URL of the Audience: |
3: Create event
Step # | Description |
---|---|
1 | Navigate to My Settings > Event Definitions and click the New Event button: |
2 | Specify a Name and click on Add Attribute under the Attributes section: |
3 | In the Attribute Name textbox, enter the value content with a data type of String, and then click the Create button: |
4: Create campaign
Step # | Description |
---|---|
1 | Navigate to the Communication tab and click the New Campaign button: |
2 | Enter a name, choose the audience (created in the earlier steps), and choose SMS. Once complete, click the Save & Next button: |
3 | In the content section Type Your SMS Here: of the message, enter the following: |
4 | Scroll to the bottom and click the Edit Trigger icon, and then configure the following:
|
5 | Click the NEXT button. |
6 | Choose Scheduled Immediately with No End Date and click the Launch Campaign button. |
Performance testing
Performance test environment specifications
2 VMs with 8 cores and 32GB of memory to be used for RPI (2 nodes)
1 VM with 4 cores and 16GB or memory to be used for RPDM
1 VM with 2 cores and 8GB of memory to be used for Realtime (supporting queue listener sends)
Azure SQLDB elastic pool instance for the marketing and ops database
Snowflake Datawarehouse (v7.28.0)
X-Small warehouse with single cluster
Snowflake ODBC driver (3.00.02.00)
Azure Service Bus Queue Provider
RPI application settings
Volume test scenarios
Scenario | Details |
---|---|
SMS Batch Sends |
|
Concurrent Sends |
|
Queue Listener Sends |
mPulse can only send 1 file/record at a time. |
Inbound | Inbound records processing via callback service processor |
Functional testing results
All functional tests have been passed, and no known issues exist.
Volume test results
Batch sends
Batch Sends | Upload Contacts Time (2000 batch size) - RPI | Member List Import Status | Member list upload time | SMS Event Upload Time | Total Workflow Execution |
---|---|---|---|---|---|
1000 | 3 seconds | 5 minutes & 28 seconds | 5 minutes & 33 seconds | 13 seconds | 6 minutes & 48 seconds |
2000 | 3 seconds | 10 minutes & 50 seconds | 10 minutes & 55 seconds | 20 seconds | 12 minutes & 11 seconds |
5000 | 7 seconds | 18 minutes & 12 seconds | 28 minutes & 47 seconds | 29 seconds | 30 minutes & 33 seconds |
10000 | 9 seconds | 55 minutes & 52 seconds | 58 minutes & 4 seconds | 27 seconds | 59 minutes & 46 seconds |
Concurrent sends
Concurrent workflow running (audience size) (batch size) | Earliest start time | Longest end time | Total offer execution |
---|---|---|---|
10 (500) (2000) | 08:44:14 | 09:13:12 | 28 minutes & 58 seconds |
10 (1000) (2000) | 09:28:29 | 10:28:24 | 59 minutes & 55 seconds |
Queue listener sends
Concurrent Sends | Number Received |
---|---|
500 | 500 |
1000 | 1000 |
2500 | 2500 |
5000 | 5000 |
The total execution time for a single queue listener request is, on average, 11 seconds (from initial QL request to send request).
Inbound
Events in Queue | Callback Service Processor Execution Time (CallbackServiceProcessorNumReaders set to 1) | Callback Service Processor Execution Time (CallbackServiceProcessorNumReaders set to 10) | Channel Synchronization Execution Time |
---|---|---|---|
50K | 5 minutes & 20 seconds | 3 minutes & 11 seconds | 1 minutes & 33 seconds |
100K | 9 minutes & 21 seconds | 5 minutes | 2 minutes & 6 seconds |
100K | 46 minutes & 24 seconds | 22 minutes & 16 seconds | 10 minutes & 12 seconds |
1M | 1 hour 34 minutes & 10 seconds | 47 minutes & 56 seconds | 25 minutes & 23 seconds |
Limitations
Limitation # | Limitation Detail |
---|---|
1 | Up to 2K members can be uploaded per batch when asynchronous list upload is enabled. Up to 50 members can be uploaded per batch when asynchronous list upload is disabled. Each API call to the |
2 | Up to 2K SMS Events can be uploaded per batch when asynchronous list upload is enabled. Up to 50 SMS Events can be uploaded per batch when asynchronous list upload is disabled. Each API call to the |
3 | When uploading members to a list asynchronously, each batch (up to 2K members) will initiate a job request in mPulse. Once the job is complete, an async callback is posted to the callback URL configured in the channel and the callback system. When all batches have been processed and posted to the callback URL, RPI will initiate the Event send requests. It was observed that uploading new members to a list will take approximately 45-60 minutes to upsert a list of 10,000 recipients. If the members already exist in the list, the upsert of 10,000 recipients will complete within 1 minute. |
4 | This integration does not support two-way messaging via the mPulse Dialogue capabilities, as there are currently no APIs to interact with that product. |
Logging
Below is an example of the Interaction log for an offer using the mPulse channel:
Log | Log Entry Descriptions |
---|---|
2023/08/15 16:30:44 Action: mPulse Channel Activity: Queue deletion completed | All SMS events queues have been cleaned up successfully. |
2023/08/15 16:30:44 Action: mPulse Channel Activity: Event upload queue 'rpieventuploadxxx183271Failed1' deleted:- Success | Indicates that deletion of the SMS events queue is successful. |
2023/08/15 16:30:44 Action: mPulse Channel Activity: Attempt to cleanup Event upload queue:- rpieventuploadxxx183271Failed1 | Indicates an attempt to delete the SMS events queue. |
2023/08/15 16:30:44 Action: mPulse Channel Activity: Event upload results: | The statistical report details of SMS events upload.
|
2023/08/15 16:30:44 Action: mPulse Channel Activity: Event upload queue 'rpieventuploadxxx183271' deleted:- Success | Indicates that deletion the SMS events queue is successful. |
2023/08/15 16:30:44 Action: mPulse Channel Activity: Attempt to cleanup Event upload queue:- rpieventuploadxxx183271 | Indicates an attempt to delete the SMS events queue. |
2023/08/15 16:30:44 Action: mPulse Channel Activity: Event Upload, batch #1 with 2 record(s):- Success | Indicates that a batch of SMS events sent via API call is successful. |
2023/08/15 16:30:44 Action: mPulse Channel Activity: Fetching next event upload batch from queue 'rpieventuploadxxx183271':- Success | Indicates an attempt to retrieve the next batch of SMS events from the queue. |
2023/08/15 16:30:42 Action: mPulse Channel Activity: Sending event upload batch #1... | Indicates an attempt to send a batch of SMS events via API call. |
2023/08/15 16:30:42 Action: mPulse Channel Activity: Attempt to create queue 'rpieventuploadxxx183271Failed1':- Success | Indicates an attempt to create a new queue for SMS events just in case of any send failure. This queue will only create once during send execution. |
2023/08/15 16:30:41 Action: mPulse Channel Activity: Fetching event upload batch from queue 'rpieventuploadxxx183271':- Success | Indicates an attempt to retrieve a batch of SMS events from the queue. |
2023/08/15 16:30:41 Action: mPulse Channel Activity: Member list asynchronous import results: | The statistical report details of member list import.
|
2023/08/15 16:28:39 Action: mPulse Channel Activity: Member list import status: 0 out of 3 batch(es) uploaded. Will retry in 5 seconds... | Indicates the progress of member list batch import process. This log message will continue to poll every 5 seconds until the execution receives update. |
2023/08/15 16:28:39 Action: mPulse Channel Activity: 1 seed SMS(s) have been sent | Indicates the number of seeds has been sent successfully. |
2023/08/15 16:28:39 Action: mPulse Channel Activity: SMS campaign send results: | The statistical report details of member list upload and SMS events sent to the queue.
|
2023/08/15 16:28:38 Action: mPulse Channel Activity: Member List Upload, batch #1:- Job Id=2dad5c5e-0f08-40cf-9b4b-4f25cc54e00b | Indicates that a batch of Member list is uploaded to mPulse via API call. |
2023/08/15 16:28:38 Action: mPulse Channel Activity: Queue Event Upload (rpieventuploadxxx183271), batch #1 with 2 records:- Success | Indicates that a batch of SMS events is sent to the queue. |
Troubleshooting
Enable trace option
When Enable trace option is selected within the Advanced tab of the mPulse channel configuration, the following samples of trace HTTP request/response
log messages are generated:
Description | HTTP Request | HTTP Response |
---|---|---|
Connectivity Test and Queue Listener Sends | mPulse Channel Trace HTTP Request Version :6.6.0.0 Category: Plugin Trace | mPulse Channel Trace HTTP Response Raw Content: Version :6.6.0.0 Category: Plugin Trace |
Asynchronous Member Upload | mPulse Channel Trace HTTP Request Version :6.6.0.0 Category: Plugin Trace | mPulse Channel Trace HTTP Response Raw Content: Version :6.6.0.0 Category: Plugin Trace |
SMS Event Upload | mPulse Channel Trace HTTP Request Version :6.6.0.0 | mPulse Channel Trace HTTP Response Raw Content: Version :6.6.0.0 |
SMS Event Upload Status | mPulse Channel Trace HTTP Request Version :6.6.0.0 | mPulse Channel Trace HTTP Response Raw Content: Version :6.6.0.0 |
Enterprise library logging
To add additional logging mechanism using the Enterprise library logging at the Callback Service web app level, please do the following:
Rename the file below. You should find this file within
mPulseCallbackServiceWebAPI\App_Config
directory.
fromEnterpriseLibrary.Logging.ExceptionHandling.Example
toEnterpriseLibrary.Logging.ExceptionHandling
The file extension should remain the same.The callback service should be able to generate log files within the
mPulseCallbackServiceWebAPI\App_Logs
directory.Perform status check of the callback service and make sure it is working as expected.
To do this, you need to use either Fiddler trace or Postman by calling the API endpoint below usingGET
method.https://<HOST NAME OR IP ADDRESS>/mPulseCallbackServiceWebAPI/status/<CLIENT ID>
Common questions
Q | Which error codes are retry-able? |
A |
|
Q | What is the current re-try strategy employed if API requests to mPulse fail? |
A | If API request fails, mPulse connector employed Exponential Backoff re-try strategy. |
Q | What are the Queue providers supported for Event upload content queue path? |
A | Azure ServiceBus/Storage Queue |
Q | What is the character limit of a message and what happens if the text for the SMS message exceeds the limit? |
A | GSM (English template): 160 characters per segment. If over 160 characters, then there is an “invisible header” that utilizes 7 of those characters to concatenate the messages for reassembly. So, it reverts to 153 characters per segment. UCS2 (Spanish) template: 70 characters per segment. If over 70 characters, then there is an “invisible header” that utilizes 3 of those characters to concatenate the messages for reassembly. So, it reverts to 67 characters per segment. Most carriers and devices will not break up the segments into separate messages. Most smartphones & carriers now allow all the segments to display as one message. Older devices, like a Nokia, will break them apart, and there are some smaller carriers that will still display each segment as a separate message. |