iframe post api user guide - bli messagingblimessaging.com/pdf/iframe post api - user guide...

iFrame Post API User Guide

1 Confidential


iFrame Post API Revision 1.3.0

Document Revision 1.3.0‐2

Alert Solutions CONFIDENTIAL AND PROPRIETARY The information in this document is proprietary to Alert Solutions, Inc. The information shall not be used, copied, reproduced or disclosed

in whole or in part without written consent of Alert Solutions.

Copyright 2013 © Alert Solutions, Inc. All rights reserved.


2 Confidential

Table of Contents TABLE OF CONTENTS ...................................................................................................................................... 2

1 IFRAME INTRODUCTION ................................................................................................................ 3

2 CONSTRUCTING AN IFRAME POST ................................................................................................. 3

2.1 INITIALIZATION ................................................................................................................................... 3 2.2 POST PARAMETERS ............................................................................................................................. 3 2.3 OVERVIEW OF POST PARAMETER USAGE ................................................................................................. 8 2.4 TEST HARNESS USAGE ......................................................................................................................... 9 2.5 USAGE OF CSS STYLESHEET URL ......................................................................................................... 11 2.6 OPTIONAL CUSTOM TRACKING CODES .................................................................................................. 11

3 IFRAME UI .................................................................................................................................. 11

3.1 LIST MANAGEMENT ........................................................................................................................... 11 3.2 TEMPLATE, DOCUMENT AND RECORDING UPLOADING ............................................................................ 12 3.3 EMAIL IFRAME .................................................................................................................................. 15 3.4 VOICE IFRAMES ................................................................................................................................ 17 3.5 TEXT MESSAGE IFRAME ..................................................................................................................... 19

4 REPORTING ................................................................................................................................. 21

4.1 REPORTING PER USER ........................................................................................................................ 21 4.2 REPORTING USING TRACKING CODES, MESSAGE TYPES AND BILLING CODES ............................................... 22

5 APPENDIX A – AVAILABLE LANGUAGES ....................................................................................... 23

6 APPENDIX B – HTTP POST REQUEST EXAMPLE ............................................................................. 23


3 Confidential

1 iFrame Introduction The purpose of this platform is to provide access to Alert Solutions’ Email, Voice and SMS platforms by embedding a messaging workflow via iFrames in a white‐labeled web application. The iFrame API consists of a page that receives an HTTP POST request and, based on the parameters posted, returns pages which may be used to build and launch single or multi‐channel message jobs and request reports on completed or in‐progress jobs. The submit page’s base URL is https://weblaunch.alertsolutions.com/IFramePost/NewMessage.aspx and its POST Parameters are defined below in section 2. All Alert Solutions iFrame message creation sessions are initialized by posting to this URL. The following sections define the required steps to submit a job and then generate a report.

2 Constructing an iFrame Post

2.1 Initialization Before making a POST request to the Alert Solutions platform, it is recommended that you construct the POST body in an initialization page. Since message recipient lists are typically submitted as part of the POST in the ListData parameter (see below), and there can be a huge amount of data in these lists, properly assembling, CSV formatting and URL‐encoding the list data is the crucial first step to a successful POST. The iFrame API test harness at https://weblaunch.alertsolutions.com/IFramePost/TestForm.aspx has an embedded manual initialization page in its central iFrame, whose source can be used as an example and starting point. See Appendix B for an actual, working POST request example.

2.2 POST Parameters The API supports the following parameters:

Parameter Name Description Possible Values Required?

Username

Login to the Alert Solutions System Text given to you by your sales rep.

Yes

Password Password to Alert Solutions System Text given to you by your sales rep.

Yes


4 Confidential


SelectMessageTypes Select whether or not the user should be prompted to select the message types to send the message to. If false, the MessageTypes parameter must be filled in.

true false If no content input method is specified (true/false), The default value is “true”

Yes

MessageTypes The message types to be used for this message.

Comma‐separated list of message types, including the below possible values: Voice Email TextMessage e.g. “Voice,Email”; “Voice”; “Email,TextMessage”

If SelectMessageTypes = “false”

ListType ListType allows you to specify how a list will be selected. When Post is chosen you must upload a list via the ListData field. When UserSelect is specified, iFrame will present a list selection page following the Messaging Options page. When ListManagement is selected the user must specify a ListID (see below) of a list in the list repository.

Post, UserSelect, ListManagement

Yes

ListID If ListType is ListManagement then the user must specify the ID # of a list already uploaded to the Alert Solutions list repository.

Valid ID # of a list in the Alert Solutions list repository.

Yes, if ListType is ListManagement

ListName The filename of the list of message recipients

String, valid Windows filename i.e. TestList.csv

Yes, if ListType is Post

ListData The list data of message recipients String, valid CSV file format with a header row. Multiple custom columns are allowed.

Yes, if ListType is Post

EmailHeader The header column in the CSV file that contains the target email addresses.

A valid header delimiter in the header row of the ListData CSV

Yes, if MessageTypes contains “Email”. Required if sending an email message.


5 Confidential


TextHeader The header column in the CSV file that contains the mobile phone numbers to send text messages to.


Yes, if MessageTypes contains “TextMessage”. Required if sending a text message.

VoiceHeader The header column in the CSV file that contains the phone numbers to send voice calls to.


Yes, if MessageTypes contains “Voice”. Required if sending a voice message.

LanguageHeader The header column in the CSV file that contains the language specification. See Appendix A for a list of valid language strings.


Optional

EmailTemplateType EmailTemplateType allows the user to specify how a template will be selected. When UserEntered or UserSelect is specified, iFrame will prompt the user with a template creation or selection screen. When TemplateManagement is selected the user must specify an EmailTemplateID (see below) of a template in the template repository.

UserEntered, UserSelect, TemplateManagement

Yes

EmailTemplateID If EmailTemplateType is TemplateManagement then the user must specify the ID # of a template already uploaded to the Alert Solutions template repository.

Valid ID # of a template in the Alert Solutions template repository.

Yes, if EmailTemplateType is TemplateManagement

VoiceTemplateType VoiceTemplateType allows the user to specify how a template will be selected. When UserEntered or UserSelect is specified, iFrame will prompt the user with a template creation or selection screen. When TemplateManagement is selected the user must specify an TextTemplateID (see below) of a template in the template repository.


Yes

VoiceTemplateID If VoiceTemplateType is TemplateManagement then the user must specify the ID # of a template already uploaded to the Alert Solutions template repository.


Yes, if VoiceTemplateType is TemplateManagement


6 Confidential


TextTemplateType TextTemplateType allows the user to specify how a template will be selected. When UserEntered or UserSelect is specified, iFrame will prompt the user with a template creation or selection screen. When TemplateManagement is selected the user must specify a TextTemplateID (see below) of a template in the template repository.


TextTemplateID If TextTemplateType is TemplateManagement then the user must specify the ID # of a template already uploaded to the Alert Solutions template repository.


Yes, if TextTemplateType is TemplateManagement

EmailPages Additional page options to display when creating an email message

A comma‐separated string. Possible values: Attachments: This option displays the page for uploading attachments. If this value is omitted, no attachments are allowed.

No


7 Confidential


VoicePages Additional page options to display when creating a voice message. This parameter is case sensitive.

A comma‐separated string. Possible values: HotKey: This option displays the page for setting digit capture options. If not present, this page is omitted. texttospeech: This option allows user to use text‐to‐speech as their method of content input. WavFile: This option allows user to upload or record a wav file as their method of content input. A NOTE ON CONTENT INPUT: If no content input method is specified (texttospeech/WavFile), it is assumed that the user wants both options. If both options are present, both options are allowed. If one option is present, the other is omitted.

No

TextPages Additional page options to display when creating a text message

None. Field exists for future use.

No

TrackingCode A user’s custom tracking code that can be submitted to help identify the message.

String No

StyleSheetURL A URL to a valid stylesheet. Any valid URL to a CSS file No


8 Confidential


ReturnURL When a job is complete iFrame will return the job’s OrderID(s), CampaignName and MessageGroupID, which is data needed to retrieve job reports. These values are by default posted to and displayed by a Alert Solutions URL, but the user may substitute their own URL and iFrame will redirect to the user’s URL and post the values there. Example: If the value of ReturnURL is “http://your.url/retpage.aspx” upon completion of a job iFrame will return: http://your.url/retpage.aspx? \ eOrderID=[ID #] \ &mOrderID=[ID #] \ &vOrderID=[ID #] \ &MessagegroupID=[ID #] \ &CampaignName=[name]

A valid URL that can parse the returned HTTP post values.

No

CancelURL If a job is at any point canceled (by clicking the “Cancel” button) iFrame will close by default. If CancelURL is specified, the user will be redirected to that URL instead.

A valid URL. No

RedirectMain When the job is completed or canceled and the user is redirected to the URL in ReturnURL or CancelURL, if RedirectMain is true the redirect will occur in the parent window. If RedirectMain is false (or absent) the redirect will occur in the iFrame.

True or false (default is false).

No

Table 1

2.3 Overview of Post Parameter Usage The iFrame is configured by a few key parameters. First, if SelectMessageTypes is set to “true” then the first screen presented to the user will prompt him to check off the types of messages to send, i.e. Email, Voice and/or Text Message. The following example (Figure 1) demonstrates the page.


9 Confidential

Figure 1

If false, the MessageTypes parameter must be filled in with “Voice”, “Email” and/or “TextMessage”. MessageTypes may be set to one or all of the available types. The user will then walk through the Voice, Email and Text Messages iFrames if they are specified in the MessageTypes field. Refer to sections 3.1 through 3.3 for the Email, Voice and Text Message iFrames. Utilize the following URL for posting to the iFrame: https://weblaunch.alertsolutions.com/iFramePost/NewMessage.aspx

2.4 Test Harness Usage The following link allows you test the submission of different jobs using different parameters. It allows you to become familiar with the post parameters before embedding the iFrame post within your application. Any of the iFrames described in sections 3.1 through 3.3 can be tested using this test harness. https://weblaunch.alertsolutions.com/iFramePost/TestForm.aspx This URL displays the following page:


10 Confidential

List Management may be tested using the following URL.


11 Confidential

https://weblaunch.alertsolutions.com/iFramePost/TestListManagement.aspx Template Management may be tested using the following URL. https://weblaunch.alertsolutions.com/iFramePost/TestDocumentManagement.aspx

2.5 Usage of CSS Stylesheet URL The StyleSheetURL parameter is an optional parameter used to modify the UI as described in section 2.1. If used it must be a valid URL. All controls included in the iFrame pages have stylesheet classes associated with them. The StyleSheetURL is loaded as an include file and applied to the controls. If the CSS is not provided by the user then a default CSS is provided by Alert Solutions. Refer to the Alert Solutions iFrame Stylesheet User Guide for guidance for creating your own UI look and feel.

2.6 Optional Custom Tracking Codes The user may enter a custom tracking code in the optional TrackingCode field. You can then generate a report for all messages sent with that tracking code.

3 iFrame UI

3.1 List Management The following List Management features are available.

• ListType=Post: Submit a list by entering it in the ListData text area. • ListType=UserSelect: Present a page where the user can select a previously uploaded list. • ListType=ListManagement: Submit a list by specifying its ID number in the ListID field.

The figure below demonstrates the page where the user can select a previously uploaded list if UserSelect is chosen:


12 Confidential

3.2 Template, Document and Recording Uploading This function allows the user to upload an HTML Email template, text file for SMS or WAV file for Voice. Email jobs accept two parameters: EmailTemplateType and EmailTemplateID. EmailTemplateType has three options:

• EmailTemplateType =UserEntered: The user will be brought to the pages defined in section 3.3. • EmailTemplateType =UserSelect: Presents a page where the user can select a previously

uploaded template from the Alert Solutions Document Library. • EmailTemplateType =TemplateManagement: Submit a template referenced by the document ID

in the EmailTemplateID field. The figure below demonstrates the page where the user can select a previous uploaded list if UserSelect is chosen:


13 Confidential

Voice jobs accept two parameters: VoiceTemplateType and VoiceTemplateID. VoiceTemplateType has three options:

• VoiceTemplateType =UserEntered: The user will be brought to the pages defined in section 3.4. • VoiceTemplateType =UserSelect: Presents a page where the user can select a previously

uploaded or recorded template from the Recording Studio. • VoiceTemplateType =TemplateManagement: Submit a template referenced by recording ID in

the VoiceTemplateID field. The figure below demonstrates the page where the user can select a previous uploaded list if UserSelect is chosen:


14 Confidential

SMS jobs accept two parameters: TextMessageTemplateType and TextMessageTemplateID. TextMessageTemplateType has three options:

• TextMessageTemplateType =UserEntered: The user will be brought to the pages defined in section 3.5.

• TextMessageTemplateType =UserSelect: Present a page where the user can select a previously uploaded text file to the Alert Solutions Document Library.

• TextMessageTemplateType =TemplateManagement: Submit a text file, referenced by document ID in the TextMessageTemplateID field.

The figure below demonstrates the page where the user can select a previous uploaded WAV if UserSelect is chosen:


15 Confidential

3.3 Email iFrame The following screens are presented to the user when the “Email” message type is selected. First, a to/from screen prompts the user to enter the Message Name, Broadcast Date, Display Name, Email From address, Reply‐To address and Subject.

Figure 2


16 Confidential

After clicking the “Next” button, the following screen will prompt the user to choose or enter email content based on the value of EmailTemplateType. If EmailTemplateType is set to “UserEntered” the user can enter in the text of the email, as shown in Figure 3 below.

Figure 3

Once the user clicks “Next” the following screen will prompt the user to add attachments or to submit or cancel the job. If the EmailPages value has been set to “attachments” then Figure 4.1 is presented to the user. If the EmailPages’s value is null or blank then Figure 4.2 is presented to the user.


17 Confidential

Figure 4.1

Once the user clicks “Next” the next screen will prompt the user to edit, submit or cancel the job. Refer to Figure 4.2 below

Figure 4.2

3.4 Voice iFrames If the VoicePages field is specified then specific pages will be displayed for each Voice parameter specified such as TextToSpeech, Wav and HotKey. The following screen appears if VoicePages is set to “texttospeech”:


18 Confidential

Figure 5 ‐ Voice Pages containing Text To Speech

The following screen appears if VoicePages contains “WavFile”:

Figure 6 ‐ Voice Pages containing WavFile

The following screen appears if VoicePages contains “TextToSpeech” and “WavFile”:


19 Confidential

Figure 7 ‐ Voice Pages containing TextToSpeech and WavFile

The HotKey screen appears after the Voice Content screen. It only appears if VoicePages contains “HotKey”.

Figure 8 – Voice Pages with Hotkey

Similar pages are displayed when EmailPages and TextPages are set.

3.5 Text Message iFrame


20 Confidential

The following Text Message screens are presented to the user when the Text Message message type is selected. First, the user is prompted for Message Name, Broadcast Date and Short Code.

Figure 9

Once the user clicks “Next” the following screen will prompt the user for the content of the Text Message. Refer to Figure 10 below.

Figure 10

Once the user clicks “Next” the following screen will prompt the user to Edit, submit or cancel the job. Refer to Figure 11 below.


21 Confidential

Figure 11

4 Reporting The reporting portion of the API supports three options:

• Request a Summary report for a user. • Request a report by user and tracking code • Request a report by user, tracking code and message type

4.1 Reporting per User The per‐user report only requires a username and password. For example, the following URL syntax should be followed: https://weblaunch.alertsolutions.com/iFrame%20Post/Report.aspx?UserName=xxxx&PassWord=xxxx This summary data is provided for each Message Name for a given user:

Message Name Total Emails Sent Total Emails Bounced Total Emails Opened Total Clicks Total Calls Sent Total Calls Failed Total Text Messages Sent Total Text Messages Failed

From this displayed if a message is selected then a page will be displayed where the user can obtain per message information.

OrderID Message Name


22 Confidential

Type Total Sent Total Failed.

4.2 Reporting using Tracking Codes, Message Types and Billing Codes

The following page can be used to obtain reports on messages send with Message Type, Tracking Code and BillingCodeType. The user can also specify the return type (Option) as XML or CSV. If no return type is provided then it defaults to CSV. https://weblaunch.alertsolutions.com/iFramePost/Reporter/ReporterTest.aspx


23 Confidential

5 Appendix A – Available Languages The following table identifies the available languages which can be specified in the language column of the CSV. Afrikaans German Polish Albanian Greek Portuguese (Brazilian) Arabic Haitian (Creole) Portuguese Belarusian Hebrew Romanian Bulgarian Hindi Russian Catalan Hungarian Serbian Chinese Icelandic Slovak Chinese Simplified (Mandarin) Indonesian Slovenian Chinese Traditional (Cantonese) Irish Spanish Croatian Italian Swahili Czech Japanese Swedish Danish Korean Tagalog Dutch Latvian Thai English Lithuanian Turkish Estonian Macedonian Ukrainian Filipino Malay Vietnamese Finnish Maltese Welsh French Norwegian Yiddish Galician Persian

6 Appendix B – HTTP POST Request Example Below is the text of a valid iFrame API POST request (with Username and Password changed). Notice that a CSV‐formatted list is submitted as part of the ListData parameter, and its headers are passed in as values to the appropriate Header parameters. In this example all the parameters have corresponding values, but optional or unpopulated parameters can still be present without issue. POST https://weblaunch.alertsolutions.com/iframepost/NewMessage.aspx HTTP/1.1 Host: weblaunch.alertsolutions.com Content‐Length: 2606 Content‐Type: multipart/form‐data; boundary=‐‐‐‐‐‐my_boundary_0123456789abcdef ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="Username" ausername ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="Password" auserpassword


24 Confidential

‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="MessageTypes" email,voice,textmessage ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="ListType" Post ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="ListName" mylist.csv ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="ListData" NAME,EMAIL,CELL Adam,[email protected],4015551234 Jared,[email protected],5085554321 Kate,[email protected],7745557890 ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="EmailHeader" EMAIL ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="TextHeader" CELL ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="VoiceHeader" CELL ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="EmailTemplateType" UserEntered ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="VoiceTemplateType" UserEntered ‐‐‐‐‐‐my_boundary_0123456789abcdef Content‐Disposition: form‐data; name="SMSTemplateType" UserEntered ‐‐‐‐‐‐my_boundary_0123456789abcdef

iframe post api user guide - bli messagingblimessaging.com/pdf/iframe post api - user guide...

Documents