MUNVO’S SMS GATEWAY ADMIN GUIDESMS Gateway: User Guide Munvo Confidential – May 23, 2019 1 MUNVO...

VERSION 2.1

May 23, 2019

MUNVO’S SMS GATEWAY

ADMIN GUIDE

SMS Gateway: Admin Guide

SMS Gateway: User Guide Munvo Confidential – May 23, 2019

i

TABLE OF CONTENTS Munvo SMS Gateway .................................................................................................................................... 1

SMS Gateway Features.............................................................................................................................. 1

Who is the Munvo SMS Gateway for? ...................................................................................................... 1

About Munvo ............................................................................................................................................ 2

Office Loca�ons ..................................................................................................................................... 2

Contact Informa�on .............................................................................................................................. 2

Adobe Campaign Classic Integra�on ............................................................................................................. 3

SMS Template ............................................................................................................................................ 3

XML Template Example ......................................................................................................................... 3

External Account ....................................................................................................................................... 5

JavaScript Libraries (JS Library) ................................................................................................................. 6

Dynamic JavaScript Pages ......................................................................................................................... 6

SMS Technical Workflows ......................................................................................................................... 7

SMS Gateway Details .................................................................................................................................... 8

User Administra�on .................................................................................................................................. 8

Crea�ng a user ...................................................................................................................................... 8

Se�ngs .......................................................................................................................................................... 9

Authen�ca�on Token ................................................................................................................................ 9

API User ................................................................................................................................................. 9

Twilio Creden�als ...................................................................................................................................... 9

Configura�on Parameters ......................................................................................................................... 9

Webhooks ............................................................................................................................................... 10

What is a WebHook? ........................................................................................................................... 10

How are Webhooks used? .................................................................................................................. 10

Crea�ng/Tes�ng/Removing a Webhook ............................................................................................. 11

Se�ng a Flowchart to use a Webhook ............................................................................................... 12

Flowchart Op�ons ................................................................................................................................... 12

API Details ................................................................................................................................................... 15

External API Document ........................................................................................................................... 15

Login Session ....................................................................................................................................... 15

Campaign ............................................................................................................................................ 16

Courier ................................................................................................................................................ 16

Transac�on .......................................................................................................................................... 17

SMS Gateway: Admin Guide


ii

Architecture Diagrams ................................................................................................................................ 20

Architecture for Adobe Campaign Classic ............................................................................................... 20

High Level Architecture ....................................................................................................................... 20

Sequence Diagram .............................................................................................................................. 21

Glossary ....................................................................................................................................................... 22

Copyright © 2019 Munvo Solutions Inc. – All rights reserved. No part of this publication may be reproduced, distributed, or transmitted in any form without the prior written permission of Munvo Solutions Inc.

This document may contain confidential information the use of which by an unintended recipient is unauthorized. Any unauthorized use or disclosure is prohibited.


1

MUNVO SMS GATEWAY

The Munvo SMS Gateway allows for inbound SMS conversations that integrate with your marketing campaign solutions. The SMS Gateway has the capacity to push lists of SMS numbers to a given short code, while forming tree-like conversation paths and real-time responses to communications.

SMS GATEWAY FEATURES

Key features of the SMS Gateway include:

Simple tree-like SMS conversations, accessible through a web interface, to facilitate client tracking of specific real-time responses to inbound requests (e.g. STOP, YES, MORE) without any programming

Storage of the individual transaction history for a given short code, such as real-time responses to inbound communications (as opposed to minutes or hours when provided by alternative solutions)

A tracked history by phone number and short code to see who receives what message and when

Integration points back to your marketing solution for advanced segmentation, personalization, and feedback

Leveraging of Twilio SMS API via HTTPS for better performance and control over SMTP-based SMS providers

WHO IS THE MUNVO SMS GATEWAY FOR?

The SMS Gateway is ideal for clients who wish to facilitate and track real-time SMS conversations, configured through a browser without any coding required. Clients who may have been underwhelmed by the SMS tools in their respected marketing solutions will find SMS Gateway to be a simple and efficient way of incorporating real-time SMS conversations as part of their communications strategy.


2

ABOUT MUNVO

Munvo is a leading consulting firm that helps clients improve their marketing capabilities through a combination of technology implementations, management consulting and marketing run services.

Since 2005, Munvo has delivered more than 500,000 hours in several key industries: Banking and Investment, Insurance, Retail, Health and Pharma, Telco, High Tech and Manufacturing, and Travel and Entertainment. Our main offices are located in Montreal, Toronto, Calgary, and the US to better serve our clients across North and South America, Europe, and APAC.

In addition, our Munvo Lab develops products and connectors for Adobe, SAS, and Unica Marketing Solutions.

OFFICE LOCATIONS

Montreal Office 1400 Metcalfe Street, Suite 300 Montreal, QC Canada H3A 1X2

Toronto Office 49 Wellington St E., Suite 201 Toronto, ON Canada M5E 1C9

Calgary Office 505 8th Avenue SW, Suite 305 Calgary, AB Canada T2P 1G2

CONTACT INFORMATION

For SMS Gateway technical support please contact us at: [email protected]

File a Service Desk Request at: https://clientspectrum.atlassian.net/servicedesk/customer/portal/4

https://clientspectrum.atlassian.net/servicedesk/customer/portal/4


3

ADOBE CAMPAIGN CLASSIC INTEGRATION

The Adobe Campaign Classic (ACC) integration is designed to provide a seamless “delivery” option for users to send messages through the SMS Gateway and their desired message provider, as opposed to using the native SMTP integration provided by Adobe.

This will appear as another standard delivery template, but one that is tailored for users to leverage the functions and features provided by the SMS Gateway.

SMS TEMPLATE

An SMS Delivery Template is created during the integration of the SMS Gateway with your Adobe Campaign instance.

This template, which is the basis for the SMS Delivery box, will create options for delivery to leverage the SMS Gateway API.

The delivery template is managed as an XML source that can be modified or customized based on client needs. These options require advanced knowledge of Adobe Campaign.

To view the template XML, first open the SMS template, select “edit” on the menu bar, and “edit XML source.”

If any modifications, additions, or changes are made, please contact [email protected], as these adjustments can break the integration between Adobe Campaign and the SMS Gateway. It is strongly recommended that you seek Munvo’s assistance if you are looking to customize the SMS Gateway Delivery Template.

XML TEMPLATE EXAMPLE

1. <delivery


4

2. FCP="0" 3. _cs="[April'19] SMS Gateway Template (DM384)" 4. analysisStep="0" 5. budget-id="0" 6. budgetStatus="0" 7. builtIn="0" 8. contentEditingMode="0" 9. contentModTime="" 10. contentStatus="0" 11. deleteStatus="0" 12. deliveryCode="" 13. deliveryMode="1" 14. > 15. <properties deliveryState="0" midRemoteId="0" toDeliver="0"/> 16. <forecast simuResponseType="0" weight="5" weightType="0"> 17. <weightFormula>$(deliveryWeight)</weightFormula> 18. </forecast> 19. <scheduling 20. IPAffinity="" 21. contactDate="" 22. delayExtraction="0" 23. delayed="0" 24. expectedBudget="" 25. expectedContent="" 26. expectedEdition="" 27. expectedExternal="" 28. expectedExtraction="" 29. expectedFCP="" 30. expectedForecast="" 31. expectedTarget="" 32. extracted="" 33. extraction="" 34. reminderBudget="" 35. reminderContent="" 36. reminderEdition="" 37. reminderExternal="" 38. reminderExtraction="" 39. reminderFCP="" 40. reminderForecast="" 41. reminderTarget="" 42. validationMode="manual" 43. validityDate="" 44. webResPurged="0" 45. webValidityDate="" 46. > 47. <waves mode="0" splitDelay="86400" splitSize="20%"/> 48. <messagePreparation forecasted="0" login="" priority="0"/> 49. </scheduling> 50. <validation 51. assignEdition="0" 52. disableNotification="0" 53. externalValidation="0" 54. sandboxMode="0" 55. sandboxModeEnforced="0" 56. useBudgetValidation="1" 57. useContentValidation="1" 58. useExtractionValidation="1" 59. useFCPEmailValidation="1" 60. useFCPPaperValidation="0" 61. useFCPPhoneValidation="0" 62. useFCPSMSValidation="0" 63. useFCPValidation="1" 64. useLinkedDeliveryValidation="0"


5

65. useTargetValidation="1" 66. validationMode="0" 67. > 68. <target> 69. <validation delay="259200" type="0"/> 70. </target> 71. <content> 72. ……… 73. …….. 74. <volume duration="1" rate="100"/> 75. <indicators processed="0" sent="0" success="0"/> 76. <mapping 77. _cs="Recipients (nms:recipient)" 78. blackListAgency="@blackList" 79. blackListEmail="Iif(@blackList!=0, 1, @blackListEmail)" 80. blackListFax="Iif(@blackList!=0, 1,@blackListFax)" 81. blackListPaper="Iif(@blackList!=0, 1,@blackListPostalMail)" 82. blackListPhone="Iif(@blackList!=0, 1,@blackListPhone)" 83. blackListSms="Iif(@blackList!=0, 1,@blackListMobile)"

EXTERNAL ACCOUNT

The external account is the basis for connecting to the SMS Gateway.

Primary areas to pay attention to:

The user “ac-admin” is used to connect to the SMS Gateway, as well as a password to login (and retrieve an API token for repeated logins).

Server field is used to point to your hosted instance of the SMS Gateway.

The second tab with configuration is the “JavaScript used in connector” field, which indicates the custom JavaScript libraries that will be leveraged by the SMS Gateway.


6

This SMS Gateway integration leverages the JavaScript library stored in the link below.

JAVASCRIPT LIBRARIES (JS LIBRARY)

The JavaScript Libraries, created to meet the needs of this custom integration, are stored here. They can be customized to add or limit functions (within the constraints of the Adobe Campaign JavaScript functions).

Core definition does not a standard implementation with all features

Modifying this library can break the SMS Gateway integration. If you would like to add new options or modify existing ones, please contact Munvo for support.

DYNAMIC JAVASCRIPT PAGES

Dynamic JavaScript pages, while not provided “OOTB,” are useful for enabling key functions in Adobe Campaign – namely, webhook endpoints. The SMS Gateway is able to make a webhook in Adobe Campaign based on some event.


7

For example, when “a user provides an access card id,” the SMS Gateway calls a JSSP page (Dynamic JavaScript page) to determine if this ID card # is valid, and then sends the SMS Gateway to the correct node in a tree to carry on the conversation.

This allows Adobe Campaign to handle all personalization and segmentation/decisioning logic, while the SMS Gateway handles delivery of SMS in real time.

SMS TECHNICAL WORKFLOWS

The SMS Gateway integra�on includes technical workflows used to integrate data back into Adobe Campaign.

Default configura�on is to pull every 3 hours, but this can be customized to reflect your needs.

There are three main integra�on points:

1. Get Status Batch Send

Table: broadLog

Action: Updates the Adobe Campaign broadLog table with a status related to the success of the batch SMS delivery.

2. Get Status Outbound

Table: gatewayOutbound

Action: Inserts all messages sent by the gateway that did not originate in Adobe Campaign (replies) to a custom table.

3. Get Status Inbound

Table: gatewayInbound

Action: Inserts all messages received by the gateway (including who, and which number they came into) to a custom table.


8

SMS GATEWAY DETAILS

USER ADMINISTRATION

As an administrator, you can create new users and modify users’ roles.

CREATING A USER

To create a new user, navigate to the user table under the “options (…)” menu in the top right and select “Users.”

On the user menu, you can select “Add New User” from the top of the user table.

Please provide a unique username, a password (with a confirmation password), and a role.

Active: Indicates that this user can login to the SMS Gateway.

Force Password Reset: Forces user to reset password upon login.

User Role

Has access to edit/modify flowcharts and reset their own password.

Admin Role

Has access to create users and webhooks, as well as modify configuration. Admin users can modify flowcharts to change/add the setup webhooks to other systems. This is not available to user roles.


9

SETTINGS

This section of the application has four submenus where you can modify the global behavior of the SMS Gateway and add configuration inbound/outbound integrations.

AUTHENTICATION TOKEN

This is your current user token, leveraged for future calls.

API USER

The special user “ac-admin” contains a “static” API token that is generated at the application’s start time. It does not change from login-to-login, which makes it ideal for API usage, as well as usage by other systems. While it supports concurrent access easily, keep in mind that the “LOGIN” API call must always be made before making future API calls.

TWILIO CREDENTIALS

This is where you can configure the SMS Gateway access to the Twilio API. If a new API key is generated, this must be updated to allow the SMS Gateway to send messages.

SMS Gateway will indicate whether or not the credentials are valid.

CONFIGURATION PARAMETERS

Courier

URL

This is the URL of the Twilio API

Default: https://api.twilio.com/2010-04-01

User

The user for the Twilio API

Default: An encrypted variable of the default Twilio User

Password

The encrypted value of the Twilio Credentials

Reserved

Keyword

A list of “reserved words” (often separated by commas) for the following events

Start

“Start messages”

Default: “start, yes, stop”

This only takes effect in short code numbers

Stop


10

“Stop Messages”

Stop, stop all, unsubscribe, cancel, end, quit

Help

“Help or information messages”

Help, info

JWT

Expiration time in minutes

How long a session will stay open

Batch

Update

Time Interval

How often to check the status of message delivery from Twilio (minutes) (e.g. message send failure/success, etc).

Retrieval Interval

The number of records to select for transactions that are considered in "progression" status

WEBHOOKS

WHAT IS A WEBHOOK?

A webhook is a method of integration through which a system (in this case, the SMS Gateway) can inform some other system of the events occurring within it. Rather than “asking” the SMS Gateway if someone has performed an action, or completed some portion of a conversation, we can notify another system that the event has occurred without delay.

This reduces wasted resources from polling-based approaches with repeated data requests.

HOW ARE WEBHOOKS USED?

Webhooks are used to notify other systems that a person has performed some action with a flowchart.

For example, our conversation flow has a request for the user identification number. Based on the user’s response to this message, we may want to prompt said user for a new # (if the input was invalid) or offer the user a personalized message.

The webhook allows us to immediately notify another system that a card validation event has occurred. Below is a sample JSON webhook response:


11

Webhook Example

1. { 2. "flowchartName":"myFlowchart", 3. "shortCode":"12345", 4. "nodeName":"Promotion Code", 5. "phone":"1-222-333-4444", 6. "usermessage":"Y", 7. "systemResponse":"Here is your promotion code #09876", 8. "timestamp":YYYY-MM-DD HH:mm:ss 9. }

CREATING/TESTING/REMOVING A WEBHOOK

API URL: The URL path to call for this webhook

JSON/XML: The desired message format (JSON/XML)

You can also select the dropdown list of current APIs, URLs, as well as the “Test URL” (to validate if the URL is responding) and “Remove URL” for any API endpoint you no longer wish to use.

Webhooks are assigned to each flowchart, and administrative users have permission to enable specific nodes to fire a webhook. This is optional, as webhooks are not required for functional conversation.


12

SETTING A FLOWCHART TO USE A WEBHOOK

At the top of the flowchart page, you will see a dropdown that allows you to select the destination for all webhooks of this flowchart.

Within any node of the flowchart, there is the “Enable Webhook” option, which allows the SMS Gateway to send a webhook call to the destination endpoint in the JSON/XML format specified above.

FLOWCHART OPTIONS

Reserved keywords are the core “must apply” keywords that must be handled before the SMS conversation tree is verified.

Keywords:

Opt-out (Stop, Unsubscribe)

Opt-in (Start, Yes, Unstop)

Help (Help, Info).


13

If using a long code with Twilio as your message provider, Twilio will provide a default Opt-In/Opt-Out/Help message, without the capacity to intervene.

If using a short code, you can customize the keywords associated with these options, as well as their respective reply messages.

Session expiration allows you to determine when a phone number is no longer valid and must be reset within the conversational session. There are two options that can be enabled:

Customer reaches a terminal node

When a customer reaches a node with no children, the phone number will have its session reset.

Customer is inactive in any node for X hour(s)

If a user is inactive for a defined period, the session will restart.

Optional: Include a session expiration message (applied in terminal node and inactive events).


14

Catch All Response is used to handle messages that do not match any expected responses (including reserved keywords). It is useful to inform users when they have provided an invalid response. By enabling this option, the SMS Gateway will reply with the “Catch All Response Message” (a customizable SMS message).

The session reset function is used for testing. When testing, you may want to restart a phone number’s session in order to test again/try different routes.

Please enter your full phone number e.g. (14167771234) into the phone number field and press “Reset.”


15

API DETAILS

The SMS Gateway provides a consumer facing API that allows users to:

Send messages

Authenticate a session

Receive the delivery status

Request details for reporting/tracking

This RESTFUL API is available at https://<application-url>/api/campaign. Note that the destination endpoint will vary based on the environment.

For further details or questions, please contact [email protected].

EXTERNAL API DOCUMENT

LOGIN SESSION

POST /api/session

Description: Login user

Request Body (JSON)

Name Description Type

username Username used to login String

password Password used to login String

Response Body (JSON)


loggedIn 1 if successful, 0 if unsuccessful Integer

username Username of logged-in user String

rolename Role that the user belongs to JSON Object

jwtToken Access token String

DELETE /api/session

https://munvo.sharepoint.com/sites/Munvo/Products/SMS%20Gateway/1%20Marketing/01%20Documentation/Admin%20Guide/[email protected]


16

Description: End the user’s session (logout)



ok Logs the user out successfully Boolean

CAMPAIGN

POST /api/campaign

Description: Destination of Twilio SMS replies

Request Body (JSON)


from From phone number String

to To phone number String

body Message body String

COURIER

POST /api/courier/tree

Description: Register batch of phone numbers into the SMS Gateway tree

Request Body (XML)


phoneTo Phone number SMS will be sent to String

phoneFrom Phone number SMS derives from String

broadlogid Broadlog ID String

reassignFlag Re-assigns phone number to top of the tree

String

nodeName Assigns phone number to specific node String


17

body SMS to be sent out String



ok Processing batch Boolean

receivedTimestamp Timestamp of batch about to be processed

Timestamp (string)

POST /api/courier/provider

Description: Bypass SMS Gateway tree and send SMS directly to Twilio provider

Request Body (XML)


phoneTo Phone number SMS will be sent to String

phoneFrom Phone number SMS derives from String


body SMS sent out to provider String



ok Processing batch Boolean

receivedTimestamp Timestamp of batch about to be processed

Timestamp (string)

TRANSACTION

GET /api/transactions/batchstatus/{lastCheckedTime}

Description: Return the status of the batch at a given timestamp


18

Response Body (CSV)



status Status of SMS String

lastmodified Last �me transac�on record was updated string

nodeName Name of node in tree String

GET /api/transactions/inbound/{lastCheckedTime}

Description: Return the status of the inbound SMS at a given timestamp

Response Body (CSV)


id Transac�on ID String

phone Phone number SMS was sent to String

campaignID Short Code or Long Code String

status Status of SMS String

lastModified Last �me transac�on record was updated String

usermessage SMS sent out to provider String

nodeName Name of node in tree String

GET /api/transactions/outbound/{lastCheckedTime}

Description: Return the status of the outbound SMS at a given timestamp

Response Body (CSV)


id Transac�on ID String

phone Phone number SMS will be sent to String


19

campaignId Short Code or Long Code String

status Status of message String

lastmodified Last �me transac�on record was updated String

systemresponse SMS sent out to provider String

nameNode Name of node in tree String


20

ARCHITECTURE DIAGRAMS

The following architecture diagrams demonstrate how the SMS Gateway enables communication between a marketing automation system, or an Amazon-hosted application cluster, and the messaging service provider.

ARCHITECTURE FOR ADOBE CAMPAIGN CLASSIC

HIGH LEVEL ARCHITECTURE

Note: Twilio communication to SMS Gateway requires the addition of a webhook URL within your Twilio configuration.


21

SEQUENCE DIAGRAM

The following sequence diagram provides details on the underlying logic that the SMS Gateway adopts, based on the outbound send (outbound batch), inbound messages (user replies), and how the webhook events work.


22

GLOSSARY

Admin Role: An SMS Gateway administrator who can create and modify users, webhooks, and flowcharts

Adobe Campaign®: A marke�ng solu�ons pla�orm that allows users to personalize, deliver, and manage cross-channel campaigns

API URL: The URL path to call for a par�cular webhook

Authen�ca�on Token: A security technique that authen�cates users atemp�ng to log in to SMS Gateway by providing them with a security token

Conversa�on Path: A way for marketers to track and collect informa�on from various Mul�media Message Service (MMS) or Short Message Service (SMS) conversa�ons between sender and recipient, to make connec�ons and observa�ons

Conversa�on Tree: A tree-like naviga�on, or path, used to dive into a par�cular conversa�on

Delivery Template: A template that captures all relevant informa�on about the sender and recipient during a par�cular Mul�media Message Service (MMS) or Short Message Service (SMS) conversa�on

Dynamic JavaScript Page (JSSP): A Java run�me library used to execute JavaScript on a web server

Flowchart Op�ons: Allows users to customize behaviour of the SMS Gateway for things like testing a phone number, modifying or viewing default STOP/START/HELP messages, as well as customer expiration options

FROM numbers: The source number from which messages derive (created and linked in the delivery layer)

HTTPS: Hypertext Transfer Protocol Secure, an extension of the Hypertext Transfer Protocol, required for securing the data in transit (communica�ons) online

JWT (JavaScript Object Nota�on – JSON WebToken): A security feature generated as part the SMS Gateway

Keywords: Words that provide additional SMS options

Long Code: Standard North American phone number (10 digits) used to send and receive Mul�media Message Service (MMS) or Short Message Service (SMS) communica�ons

Mul�media Message Service (MMS): Typically used to transmit images, videos, and other forms of mul�media

Mobile Messaging Provider (MMP): A network that provides mobile messaging services (SMS and MMS) to other businesses or providers

Nodes: The point where pathways intersect within a conversa�on tree


23

Request Body: Objects sent to the SMS Gateway

Response Body: Object returned from the server after making

Short Code: Standard North American short digit sequences (5-6-digit numbers) used to address messages in both the Short Message Service (SMS) and Mul�media Message Service (MMS) communica�ons

Short Message Service (SMS): Typically referred to as text messaging, SMS allows for the transmission of short messages through mobile devices

Sinch® (Formerly CLX): A telecommunica�ons and cloud communica�ons pla�orm that allows developers to perform Mul�media Message Service (MMS) or Short Message Service (SMS) func�ons and embed this data into other apps or devices. See htps://www.sinch.com/ for more informa�on.

Simple Mail Transfer Protocol (SMTP): A communica�on protocol for sending electronic mail transmission between servers.

SMS Template: The SMS Template simplifies and provides a centralized store for any personalized messages leveraged by the SMS Gateway (within a conversa�on tree or not). The SMS Template contains a number of placeholders to apply variables. These variables can then be subs�tuted to provide a more personalized messaging feel: e.g. “Hello Bob, thanks for replying.”

Targe�ng and Workflow Tab: A tab within the SMS Delivery Form used to create an SMS Delivery in Adobe Campaign

Twilio®: A cloud communica�ons pla�orm service that allows developers to perform communica�on func�ons (SMS, MMS) through web service APIs. See htps://www.twilio.com/ for more informa�on.

User Role: An SMS Gateway administrator who has the ability to modify flowcharts

Webhook: The process of triggering custom call backs to a marke�ng automa�on so�ware

https://www.sinch.com/

https://www.twilio.com/

MUNVO’S SMS GATEWAY ADMIN GUIDESMS Gateway: User Guide Munvo Confidential – May 23, 2019 1 MUNVO...

Documents

Transcript of MUNVO’S SMS GATEWAY ADMIN GUIDESMS Gateway: User Guide Munvo Confidential – May 23, 2019 1 MUNVO...