Upload
dokhuong
View
248
Download
2
Embed Size (px)
Citation preview
iFrame Post API User Guide
1 Confidential
iFrame Post API User Guide
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.
iFrame Post API User Guide
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
iFrame Post API User Guide
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
iFrame Post API User Guide
4 Confidential
Parameter Name Description Possible Values Required?
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.
iFrame Post API User Guide
5 Confidential
Parameter Name Description Possible Values Required?
TextHeader The header column in the CSV file that contains the mobile phone numbers to send text messages to.
A valid header delimiter in the header row of the ListData CSV
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.
A valid header delimiter in the header row of the ListData CSV
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.
A valid header delimiter in the header row of the ListData CSV
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.
UserEntered, UserSelect, TemplateManagement
Yes
VoiceTemplateID If VoiceTemplateType 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 VoiceTemplateType is TemplateManagement
iFrame Post API User Guide
6 Confidential
Parameter Name Description Possible Values Required?
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.
UserEntered, UserSelect, TemplateManagement
TextTemplateID If TextTemplateType 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 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
iFrame Post API User Guide
7 Confidential
Parameter Name Description Possible Values Required?
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
iFrame Post API User Guide
8 Confidential
Parameter Name Description Possible Values Required?
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.
iFrame Post API User Guide
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:
iFrame Post API User Guide
10 Confidential
List Management may be tested using the following URL.
iFrame Post API User Guide
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:
iFrame Post API User Guide
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:
iFrame Post API User Guide
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:
iFrame Post API User Guide
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:
iFrame Post API User Guide
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
iFrame Post API User Guide
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.
iFrame Post API User Guide
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”:
iFrame Post API User Guide
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”:
iFrame Post API User Guide
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
iFrame Post API User Guide
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.
iFrame Post API User Guide
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
iFrame Post API User Guide
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
iFrame Post API User Guide
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
iFrame Post API User Guide
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