W2CDevelopersGuide 1535119034 W2c Developers Guide

1535119034_w2c-developers-guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 28

Cloud Contact Center
Software
Five9 and the Five9 logo are registered trademarks of Five9 and its subsidiaries in the United States and other countries. Other marks and brands may
be claimed as the property of others. The product plans, specifications, and descriptions herein are provided for information only and subject to change
without notice, and are provided without warranty of any kind, express or implied. Copyright © 2017 Five9, Inc.
Web2Campaign
Developers and Administrators Guide
August 2017
Five9 Web2Campaign uses POST and GET requests to automatically add
records to dialing lists used in outbound or autodial campaigns.
ii Web2Campaign • Developer’s and Administrator’s Guide
About Five9
Five9 is the leading provider of cloud contact center software, bringing the power of the
cloud to thousands of customers and facilitating more than three billion customer
interactions annually. Since 2001, Five9 has led the cloud revolution in contact centers,
delivering software to help organizations of every size transition from premise-based
software to the cloud. With its extensive expertise, technology, and ecosystem of
partners, Five9 delivers secure, reliable, scalable cloud contact center software to help
businesses create exceptional customer experiences, increase agent productivity and
deliver tangible results. For more information visit www.five9.com.
Trademarks
Five9®
Five9 Logo
Five9® SoCoCare™
Five9® Connect™
iii Web2Campaign • Developer’s and Administrator’s Guide
Contents
What’s New.................................................................................v
Chapter 1
About the Web2Campaign Integration ................................................1
Limits for Bulk Processing.......................................................................... 1
Requirements ........................................................................................ 2
Administrator.................................................................................... 2
Developer........................................................................................ 2
Chapter 2
Preparing to Use Web2Campaign ......................................................3
Contact Fields........................................................................................ 3
Dialing Lists........................................................................................... 4
Setting the Dialing Order...................................................................... 4
Using Dialing Lists in the E.164 Format ..................................................... 4
Campaigns ............................................................................................ 5
Campaign Profiles ................................................................................... 5
Chapter 3
Selecting and Configuring Parameters................................................6
Required Parameters................................................................................ 6
Optional Parameters ................................................................................ 6
Storing Alternate Phone Numbers: number2 and number3 .............................. 7
Using the Country Code: F9CountryCode ................................................... 7
Creating a Unique Key: F9key ................................................................ 7
Updating the CRM: F9updateCRM ............................................................ 8
Displaying Results: F9retResults and F9retURL ............................................ 9
Scheduling Calls: F9CallASAP, F9TimeToCall, and F9TimeFormat.....................10
F9CallASAP.................................................................................10
F9TimeToCall..............................................................................10
F9TimeFormat.............................................................................10
Returning Result Codes About Contact Records ..........................................12
VCC Contact Fields .................................................................................13
Chapter 4
Formatting HTTP Requests............................................................ 14
Using the GET Method .............................................................................14
Selecting the Parameters.....................................................................14
Syntax With Required Parameters Only ...............................................14
Syntax With Optional Parameters......................................................14
Creating the URL...............................................................................15
iv Web2Campaign • Developer’s and Administrator’s Guide
Examples........................................................................................15
F9retResults and F9retURL..............................................................15
F9key .......................................................................................16
Date and Time Formats.......................................................................16
F9updateCRM...................................................................................17
Using the POST Method............................................................................18
Creating an HTML Form.......................................................................18
Testing the Form...............................................................................19
Verifying the Results...............................................................................19
Appendix A
Result Codes.............................................................................. 21
vWeb2Campaign • Developer’s and Administrator’s Guide
Chapter 3
What’s New
This table lists the changes made in the last six releases of this document:
Release Changes
August 2017 Added Returning Result Codes About Contact Records.
July 2017 Added HTTP response codes and recommended actions to Result Codes.
June 2017 Added Result Codes 602 and 603, which are returned if problems occur with a list.
August 2016 Corrected the Campaigns section.
March 2016 Corrected the links to the complex Web form in Creating an HTML Form.
August 2015 Clarified how the call time value is applied in F9TimeToCall and how this parameter is
used during maintenance.
July 2015 Clarified how to use custom date and time contact fields. For more information, see VCC
Contact Fields.
May 2015 Removed result code 705.
1Web2Campaign • Developer’s and Administrator’s Guide
Chapter 1
About the Web2Campaign Integration
Five9 Web2Campaign enables you to add or update records in a Five9 list used for dialing
in an outbound or autodial campaign. Web2Campaign can send HTTP POST and GET
requests from a contact or lead management application or from a Web form in which a
contact enters information. If the uploaded number is on the local DNC list of the domain,
the number is not dialed.
Limits for Bulk Processing
For each domain, the maximum number of upload requests allowed is 500 every minute,
20000 every hour, and 300000 every day.
If you consistently need to import large numbers of leads in each request, use the
Configuration Web Services API instead. For more information, contact your Five9
representative, and see the Configuration Web Services API Reference Guide.
Each addition to a campaign is counted even if all additions come from the same list. If
you want to submit multiple requests to multiple lists during each hour, and if each list is
used in a different campaign, use this formula to calculate the total number of requests in
each hour:
R1*C1 + R2*C2 +... Rn*Cn = 20000
R = Request
C = Campaign
Example 1: If you want to submit requests to a list that is used in two campaigns, do
not submit more than 10000 requests to the list during each hour.
Example 2: If you want to submit requests to four lists that are used in one campaign,
do not submit more than 20000 requests to the combined lists during each hour.
Each list should not receive more than 5000 additions.
Example 3: If you want to submit requests to two lists that are used in different sets
of 10 campaigns (20 campaigns in total), do not submit more than 1000 requests to
the combined lists during each hour.
2Web2Campaign • Developer’s and Administrator’s Guide
About the Web2Campaign Integration Requirements
concurrent requests
Web2Campaign can process up to 20 requests concurrently. To ensure that all data is
delivered to the list, the flow of traffic may be restricted when the system is very busy. If
the server cannot process a request, you receive an HTTP 5XX server error. If you receive
too many errors, Five9 recommends that you add a short delay between requests to
enable the server to keep up with your requests.
Requirements
The VCC administrator and the Web2Campaign developer must work together to design
the implementation.
Administrator
You must provide the following required information to the developer. All elements are
case sensitive:
Your Five9 domain name.
The name of the lists that you want to use with Web2Campaign. Your developer
implements a separate request for each list that you provide.
The names of all contact fields listed in the Five9 Administrator VCC that you
want to include in the request, for example: first name, last name, and address.
In addition, if you want to give dialing precedence to numbers added with
Web2Campaign, ensure that your developer uses the optional F9CallASAP and
F9TimeToCall parameters.
Developer
To implement Web2Campaign, you must know how to create HTTP POST and GET
requests in a Web form or with a third-party application.
To construct requests, you must obtain this information from your Five9 administrator.
All elements are case sensitive:
Your Five9 domain name.
The name of the lists that you want to use with Web2Campaign.
The names of all contact fields to include in the request, for example: first name,
last name, and address.
3Web2Campaign • Developer’s and Administrator’s Guide
Chapter 2
Preparing to Use Web2Campaign
This chapter describes for VCC administrators how to prepare the elements to add to
Web2Campaign requests.
Contact Fields
Dialing Lists
Campaigns
Campaign Profiles
Contact Fields
You can use up to 64 default and custom contact fields in Web2Campaign requests. If you
plan to use custom date and time contact fields, combine dates and time formats as you
need. The default format is the first pair of options in the figure: yyyy-MM-dd
HH:mm:ss.SSS. For more information, see the Contact chapter of the Basic
Administrators Guide.
Preparing to Use Web2Campaign Dialing Lists
4Web2Campaign • Developer’s and Administrator’s Guide
Dialing Lists
Web2Campaign contains parameters that apply to the content and format of your lists.
Setting the Dialing Order
In a campaign list, numbers are dialed in the order in which they are added to the list,
starting from the top (first in, first out), or in the sort order that you specify in the
campaign profile.
If a list has a backlog of numbers to be dialed, the numbers added first are dialed before
any numbers added with Web2Campaign. However, if you want to give precedence to
numbers added with Web2Campaign, ensure that your developer uses the F9CallASAP
and F9TimeToCall parameters:
F9CallASAP: numbers are dialed as soon as possible regardless of list position.
F9TimeToCall: numbers are dialed at the time specified if possible.
Using Dialing Lists in the E.164 Format
If your domain is not enabled for the E.164 format for international phone numbers, your
agents must enter 10 digits to conform to the North American Numbering Plan. This
section does not apply to you.
If your domain is enabled for the E.164 format, your agents need to enter phone numbers
for all calls according to your configuration: in your national format or up to 15 digits,
starting with the plus (+) sign and the country code.
The E.164 format is used to route calls, process lists, and display numbers in your
applications and reports. When you upload a list, all non-numeric characters, such as
dots, dashes, spaces, and parentheses, and the country prefix are removed. Numbers are
stored in the E.164 format, starting with the plus sign.
You may also configure in the VCC a national phone number format. In this case, you can
upload lists that contain numbers in E.164 format, in your national format, or both. If you
do not specify a format, the VCC uses the E.164 format for all numbers. For more
information, see the Basic Administrators Guide. For example, if you operate in the UK,
these numbers are processed as follows:
Preparing to Use Web2Campaign Campaigns
5Web2Campaign • Developer’s and Administrator’s Guide
To use the E.164 format, ensure that your developer uses the F9CountryCode parameter.
If the parameter is omitted, the country specified for your domain is used.
Campaigns
To create an outbound or autodial campaign with Web2Campaign, proceed as usual.
When a campaign runs out of numbers, it becomes inactive until records are inserted in
the list. At that time, the new numbers are dialed if the campaign is running. Records
submitted to lists of campaigns that are not running are not dialed until the campaign is
started.
Campaign Profiles
List records processed by Web2Campaign with the F9CallASAP parameter are put into a
special queue. In the Dial ASAP List Record Queue for Web APIs setting of the Campaign
Profile properties, you can specify the time-out for the new records and select the sort
order for the ASAP queue as follows:
FIFO: first in, first out.
LIFO: last in, first out.
•Contact Record Fields.
After refreshing its cache, the dialer inserts the new records in the correct position.
Phone number format How the number is processed
International format 1Belgium phone number is added to a list: 0032.20.3456.7899
2Phone number is processed in VCC: International prefix (00)
and non-numeric characters are removed. Plus sign is added.
3Stored number: +322034567899
National format 1UK phone number is added to a list: 02034567899
2Phone number is processed in VCC: National prefix (0) and
non-numeric characters are removed. UK country code and
the plus sign are added.
3Stored number: +442034567899
No specified format Number stored in E.164 format.
6Web2Campaign • Developer’s and Administrator’s Guide
Chapter 3
Selecting and Configuring Parameters
This chapter describes for developers the Web2Campaign parameters and contact fields
to include in requests:
Required Parameters
Optional Parameters
VCC Contact Fields
Required Parameters
The request is valid if you use only these parameters:
F9domain: Domain name provided by your VCC administrator.
F9list: Campaign lists provided by your VCC administrator. You can include only
one list in each request, but you can create as many requests as you need to
accommodate multiple lists and request conditions. The lists must be specific to
Web2Campaign.
number1: Primary phone number associated with the lead.
Optional Parameters
You can use single or combined parameters as you need.
Storing Alternate Phone Numbers: number2 and number3
Using the Country Code: F9CountryCode
Creating a Unique Key: F9key
Updating the CRM: F9updateCRM
Displaying Results: F9retResults and F9retURL
Scheduling Calls: F9CallASAP, F9TimeToCall, and F9TimeFormat
Use boolean values as follows:
false, 0, no, or off
true, 1, yes, or on
7Web2Campaign • Developer’s and Administrator’s Guide
Selecting and Configuring Parameters Optional Parameters
Storing Alternate Phone Numbers: number2 and
number3
If available, include in your request the number2 and number3 parameters as the first and
second alternate phone numbers associated with the lead.
Using the Country Code: F9CountryCode
You may use this parameter only if your domain is enabled for the E.164 phone number
format. Otherwise, the parameter is ignored. This parameter enables you to specify the
country code with the two-letter codes defined in ISO 3166-1 that should be used to
convert numbers to the E.164 format. The parameter applies to all numbers in the
request, including custom phone fields. If you omit this parameter, the country specified
for your domain is used.
Before using this parameter, consult your VCC administrator to ensure that your lists are
formatted correctly. These examples show how you might use this parameter, depending
on the country code specified in your configuration:
Example GET
number1=+0032.20.3456.7899&F9CountryCode=BE
number1=02034567899&F9CountryCode=GB
number1=9255551212&F9CountryCode=US
Example POST
<input type="hidden" name="number1" value="+0032.20.3456.7899">
<input type="hidden" name="F9CountryCode" value="BE">
Creating a Unique Key: F9key
This parameter enables you to combine multiple contact fields to create a unique key to
locate the record. If you omit this parameter, the default key is the number1 parameter.
Syntax for a key that contains one field:
Example GET
F9key=acctnbr&acctnbr=555111222
Example POST
<input type="hidden" name="F9key" value="acctnbr">
<input type="hidden" name="acctnbr" value="555111222">
Syntax for a key that contains two fields, such as first and last names:
Example GET
8Web2Campaign • Developer’s and Administrator’s Guide
Selecting and Configuring Parameters Optional Parameters
F9key=first_name&F9key=last_name&first_name=jon&last_name=smith
Example POST
<input type="hidden" name="F9key" id="F9key" value="first_name">
<input type="hidden" name="F9key" id="F9key" value="last_name">
<input type="hidden" name="first_name" id="first_name" value="jon">
<input type="hidden" name="last_name" id="last_name" value="smith">
Syntax for a key that is incremented with each post: a new record is created each
time even if the phone number is already in the database. This key ensures that
multiple posts for the same contact result in multiple calls over time. For
example, you can generate a Globally Unique Identifier (GUID).
Example HTML code that contains GUID function
<html>
<head><script>
function generateGuid(){
return 'xxxxxx-xxxx-4xxx-yxxx-xxxxxxx'.replace(/[xy]/g,
function (c){
var r = Math.random() * 16 | 0, v = c == 'x' ? r :
(r & 0x3 | 0x8);
return v.toString(16);
}
);
}
</script></head>
<body>
<input type="hidden" name="F9key" id="F9key" value="guid">
<input type="hidden" name="guid" id="guid" value="">
<input type="hidden" name="first_name" id="first_name" value="jon">
<input type="hidden" name="last_name" id="last_name" value="smith">
<script>document.getElementById("guid").value = generateGuid();
</script>
</body></html>
Updating the CRM: F9updateCRM
Use this parameter to update your CRM database with the posted information:
true: Update the CRM (default if omitted). The contact data is updated.
false: Do not update the CRM. Only the phone number is posted.
You can use this parameter with F9key. This table shows how the record and the list are
updated depending on the number of records in the database before you send the
request.
9Web2Campaign • Developer’s and Administrator’s Guide
Selecting and Configuring Parameters Optional Parameters
Example A list contains this contact record:
number1 (key) = 9995551212
first_name = Phil
If a new request contains these values:
number1 = 9995551212
first_name = Sarah
The value of F9updateCRM determines the result:
F9updateCRM=false: the record is not changed, but it is added to the list.
F9updateCRM=true: the name is changed from Phil to Sarah, and the updated
record is added to the list.
Displaying Results: F9retResults and F9retURL
Use the F9retResults parameter to indicate whether to display the result. Whether or
not you include this parameter in your request, the list is updated.
true: to display the results, include the F9retURL parameter. Two fields are
appended to the return URL:
F9errCode: 0 (zero) if successful or an error code.
F9errDesc: Text description of the code.
false: Do not display the results (default if omitted).
Database records F9updateCRM Record Created or Updated Record Added to List
0
True Created Added
False Skipped Skipped
1 (see example
below)
True Updated
Added
False Not updated
2 or more Result code 708. When multiple records match F9Key, the system
cannot decide which record to update. Therefore no changes are
made.
10 Web2Campaign • Developer’s and Administrator’s Guide
Selecting and Configuring Parameters Optional Parameters
Use the F9retURL parameter to indicate the fully qualified URL of the result page for
successful requests.
Scheduling Calls: F9CallASAP, F9TimeToCall, and
F9TimeFormat
These parameters enable you to specify the dialing time and the date and time format.
F9CallASAP
This parameter indicates whether to dial the record as soon as possible.
true: Dial the number as soon as possible.
false: Insert the number at the bottom of the list.
F9TimeToCall
This parameter indicates when to dial the record. The number is dialed at the time
specified or as soon as possible if the time has passed. During maintenance, if your
domain is moved to a backup server, this parameter is ignored until your domain is
returned to the primary server. If you use this parameter, F9TimeFormat is required.
F9TimeFormat
This parameter specifies the format of F9TimeToCall. With these parameters, the record
is updated with the time of the request, but you do not see the actual time of the
scheduled call. To see the scheduled call information in the list record, add to your
request a custom date and time contact field.
F9retResults F9retURL Result Displayed
-
True
False
- In Web form
True
False
URL In string at return URL
Redirect to return URL but no visible result
Note The call time value is applied only if the campaign exists when the record is added
to the list assigned to that campaign. However, if a campaign is created or associated
with a list after the record is added to the list, calls may be dialed sooner than the
specified value, depending on the size of the list, the position of the record in the list,
and the other parameters assigned to the list in the campaign.
11 Web2Campaign • Developer’s and Administrator’s Guide
Selecting and Configuring Parameters Optional Parameters
This table shows the possible date and time representations. In most cases, the number
of letters represents the number of characters, for example: 2013=yyyy.
This figure shows the relationship between the options for hours: H, h, K, and k.
Date and Time Components Display Letter Examples
Year Number y 2013 = yyyy; 13 = yy
Month Text M July = MMMM; Jul = MMM; 07 = MM
Week
Year
Month
Number
Number
w
W
27 = ww
2 = W
Day
Year
Month
Week in the Month
Week
Number
Number
Number
Text
D
d
F
E
189 = DDD
10 = dd
2 = F
Tuesday = EEEEEEE; Tue = EEE
Hour
Day (0–23)
Day (1–24)
Am or Pm (0–11)
Am or Pm (1–12)
Number
Number
Number
Number
H
k
K
h
12 = HH; 0 = H
6 = k; 24 = kk
10AM = KK; 0 = K (requires AM/PM)
6PM = h; 12 = hh (requires AM/PM)
Minute Number m 30 = mm; 5 = m; 05 = mm
Second Number s 55 = ss; 5 = s; 05 = ss
Millisecond Number S 978 = SSS
AM or PM Text a PM = a
AD (era) Text G G = AD
Time zone
Offset (RFC 822)
Text
Number
z
Z
PST = z
-0800 = Z
12 Web2Campaign • Developer’s and Administrator’s Guide
Selecting and Configuring Parameters Optional Parameters
This table shows possible representations for 2013-07-04 12:08:56.567 in the Pacific time
zone. The first row is the default display.
Returning Result Codes About Contact Records
The F9is93compatible parameter enables you to specify result codes 602 and 603,
which provide information about contact records.
true: Default. Replies contain result code 0 instead of result codes 602 and 603.
false: Enables result codes 602 and 603.
Formats Representations
2013-07-04 12:08:56.567 yyyy-MM-dd HH:mm:ss.SSS
12:08 PM hh:mm a
130704120856-0800 yyMMddHHmmssZ
Wed, Jul 4, '13 EEE, MMM d, 'yy
12 o'clock PM, -0800 UTC hh o'clock a, Z
0:08 PM, PST K:mm a, z
Wed, 4 Jul 2013 12:08:56 -0800 EEE, d MMM yyyy HH:mm:ss Z
Note For all new implementations, Five9 recommends that you set this parameter
to false because it will be removed in a future release.
13 Web2Campaign • Developer’s and Administrator’s Guide
Selecting and Configuring Parameters VCC Contact Fields
VCC Contact Fields
You can use as optional parameters the default contact fields and custom contact fields.
You may use up to 64 contact fields. When constructing your request, follow these rules:
Match the name, case, and format of your parameter to the field name and
format defined in the VCC.
Five9 recommends that you use this format for date and time fields, including the
time zone in you requests: yyyy-MM-dd HH:mm:ss.SSS Z
Example myDateTimeField=2015-06-30%2016:00:00.000%20GMT0
Match the format selected for the contact field in the VCC. You may add more
information than the format contains, but you may not omit information.
Example Display format in the VCC = yyyy-mm-dd hh:mm:ss
In your request, you may add milliseconds: yyyy-mm-dd hh:mm:ss.sss.
However, if you remove a part, such as seconds, you receive an error
message because they are missing.
•Omit the F9TimeFormat parameter because it does not apply to custom contact
fields.
14 Web2Campaign • Developer’s and Administrator’s Guide
Chapter 4
Formatting HTTP Requests
This chapter describes how to create requests for each list and set of conditions. In
addition to parameters and contact fields, you can add scripts to your code to determine
if the lead was successfully posted and to act on the results.
Using the GET Method
Using the POST Method
Verifying the Results
Using the GET Method
This section describes GET requests.
Selecting the Parameters
Use this syntax in your requests.
Syntax With Required Parameters Only
https://api.five9.com/web2campaign/AddToList?F9domain=<Your_
Domain>&F9list=<Your_List>&number1=<phone_number>
Syntax With Optional Parameters
Append the optional parameters to the required parameters:
https://api.five9.com/web2campaign/AddToList?F9domain=<Your_
Domain>&F9list=<Your_List>&number1=<phone_
number>&F9retResults=<value>&F9retURL=<Your_Return_Page>&first_
name=<first_name>&last_name=<last_name>
Important All elements, parameters, and contact fields are case sensitive.
Formatting HTTP Requests Using the GET Method
15 Web2Campaign • Developer’s and Administrator’s Guide
Creating the URL
You can use any Web programming language. This PHP example shows how you can add
parameters to the URL.
/* Contains the URL for your Web2Campaign requests. */
$Five9Url = "https://api.five9.com/web2campaign/AddToList?";
/* Contains the Web2Campaign parameters with placeholders for your
values. */
$Five9Params = sprintf("F9domain=%s&F9list=%s&F9retResults=1&first_
name=%s&last_name=%s&number1=%s", "Your_Domain", urlencode("Your_
List"), urlencode($contact['first_name']), urlencode($contact['last_
name']), $phoneNumbersOnly);
/* Concatenates the URL and the parameters. */
$url = $Five9Url . $Five9Params;
Examples
These examples show how the name of the lead is added to a list by using the primary
phone number and other parameters. To test your request, paste the URL in the address
field of a browser. To verify that your list has been updated, log into the VCC
administrators desktop. For instructions, see Verifying the Results.
F9retResults and F9retURL
The parameters enable you to see the result in a URL string at the location of the return
URL.
• Request:
https://api.five9.com/web2campaign/AddToList?F9domain=<Your_
Domain>&F9list=<Your_
List>&number1=9255551333&F9retResults=1&F9retURL=<Your_Return_
URL>&first_name=john&last_name=smith
•Result:
<Your_Return_URL>?F9errCode=0&F9errDesc="The request was
successfully processed"
Formatting HTTP Requests Using the GET Method
16 Web2Campaign • Developer’s and Administrator’s Guide
F9key
The combined F9key parameters create a unique key that is used to update the record
with the first and last names of the leads. In the absence of the F9retURL parameter, you
see the result in a Web form.
• Request:
https://api.five9.com/web2campaign/AddToList?F9domain=<Your_
Domain>&F9list=<Your_List>&number1=9255551333&F9key=first_
name&F9key=last_name&first_name=John&last_
name=Lamb&number1=2345678555
•Result:
Date and Time Formats
This section contains test cases with various date and time formats. You can start by using
this request, modifying it as needed for the other cases:
https://api.five9.com/web2campaign/AddToList?F9domain=<Your_
Domain>&F9list=<Your_List>&F9key=last_name&F9key=first_name&first_
name=Mary&last_name=Lamb&number1=2234567890&F9TimeToCall=2013-12-
02%2014:30:00.000&F9TimeFormat=yyyy-MM-dd%20HH:mm:ss.SSS
F9TimeToCall F9TimeFormat contactTime Result
2013-12-02
14:30:00.000
yyyy-MM-dd
HH:mm:ss.SSS
-Result code 0.
140704120856-
0800
yyMMddHHmmssZ -Result code 0.
12:08 PM hh:mm a -Result code 0.
Formatting HTTP Requests Using the GET Method
17 Web2Campaign • Developer’s and Administrator’s Guide
F9updateCRM
This section contains test cases with the F9updateCRM parameter. F9key is always the first
and last names. You can start by using this request, modifying it as needed for the other
cases:
https://api.five9.com/web2campaign/AddToList?F9domain=<Your_
Domain>&F9list=<Your_List>&F9key=first_name&F9key=last_name&first_
name=Mary&last_name=Lamb&number1=2234567890
July 4, 2014 at
12:08:56 PDT
MMMM d, yyyy at
HH:mm:ss z
- 801 = Unknow error Illegal
pattern character 't'
Any format that
matches
F9TimeFormat
Any format Any format
defined in
the VCC
Result code 0. The contact field
overrides the parameters. In the
VCC list, the modified_on time
reflects the request time, but a
new contactTime column
contains the dialing date and
time.
- - MM/dd/yyyy
h:mm a
12/2/2013
2:30 PM
Although the format specifies
two characters for the day, this
request uses only a single digit.
Result code 0.
F9TimeToCall F9TimeFormat contactTime Result
number1 number2 number3 email F9updateCRM Result
number1 - New record
number1 number2 - Updated
number1 number2 number3 True Updated
number1 number2 number3 email False Not updated
Different number1 -Updated
Formatting HTTP Requests Using the POST Method
18 Web2Campaign • Developer’s and Administrator’s Guide
Using the POST Method
This section describes how to prepare a Web form such as this one to upload leads to a
Five9 list:
Creating an HTML Form
The HTML code contains a form with POST action, parameters, and form fields. The
parameters are hardcoded and hidden. Of the visible user information, only the phone
number is a parameter.
Ensure that users cannot submit the same data multiple times. Otherwise they may be
called multiple times. For example, after the customer has submitted the data, remove
the submission button, redirect the customer, or query your database for duplicate
entries.
Validate the phone number fields. For example, Five9 would reject 111-111-1111.
Therefore, your code should reject invalid phone numbers that users try to submit. Phone
numbers can contain from 10 to 16 digits. Phone numbers outside North America start
with 011. For a JavaScript example that validates 10-digit phone numbers with regular
expressions, see complexwebform.txt.
You can use these examples to design your form:
samplewebform.txt is a basic Web form.
complexwebform.txt contains validation scripts for the phone numbers and for
the form.
Formatting HTTP Requests Verifying the Results
19 Web2Campaign • Developer’s and Administrator’s Guide
Testing the Form
To test your form, vary the input data to show how the name of the lead is successfully
updated by using the primary phone number and the other parameters. To verify that
your list has been updated with the data in your request, log into the VCC administrators
desktop. For instructions, see Verifying the Results.
Verifying the Results
The list is updated every minute. To verify the results of a successful request, look at the
contents of the list in the VCC. Phone numbers are dialed in the order in which they are
uploaded, from top to bottom. If the list is currently open, refresh its content to see the
update. Otherwise follow the steps below.
1Log into your Five9 account as an administrator.
2In the navigation pane, open Lists.
These text files would be ac-
cessible only from this doc but
would be located in the same
SF folder. This way I can show
more extensive examples that
users can copy/paste easily. Is
that OK? Currently the links
are dead because i have the
files.
this time attached
complexWebForm.txt.
Formatting HTTP Requests Verifying the Results
20 Web2Campaign • Developer’s and Administrator’s Guide
3Double-click your list.
4To verify the date and time of creation or modification of the records, scroll to
the right to the created_on and modified_on columns.
21 Web2Campaign • Developer’s and Administrator’s Guide
Appendix A
Result Codes
error code
Five9 recommends that you include error handling in your code. These codes and
descriptions are returned when you use the F9retURL and F9retResults parameters.
Example Code returned when you exceed the number of requests allowed.
F9errCode = 715
F9errDesc = Number of requests exceed the maximum allowed value: {0}.
If a required field is blank, does not have the correct case, or does not match your VCC
configuration, you receive an error code.
Example If number1 is blank, you receive error 706: At least one number should be
specified for new record.
If an optional field is blank, the request is processed successfully. However, if the optional
field does not have the correct case, contains an invalid character, or does not match your
VCC configuration, the request fails, and you receive an error code.
Example If you specify number2 that does not exist in your database, you receive
error 600: The following field(s) not exist in the CRM table: number2.
Example If you use a dash instead of leaving a field blank (number2=-), you receive
error 702.
Codes Description
Successful Post
0 The request was successfully processed.
HTTP Codes When these errors occur, send the request again after a few minutes.
If the error occurs again, add the records to a file and resend your
request manually or with the Configuration Web Services API.
404 Not Found: The requested resource was not found but may be
available in the future.
500 Internal Server Error: A generic error message returned when an
unexpected condition occurs for which no specific message exists.
Result Codes
22 Web2Campaign • Developer’s and Administrator’s Guide
502 Bad Gateway: The server received an invalid response from the
upstream server.
503 Service Unavailable: The server is unavailable. Generally, this is a
temporary state.
504 Gateway Timeout: The server did not receive a timely response from
the upstream server.
Warnings
600 The following field(s) do not exist in the CRM table: {0}
Note The missing fields are ignored when the request is processed.
The request is not rejected.
601 Sending email is not supported in this release
Errors
602 Contact record already existed. It was added to the list.
603 No new records were added: the record is already in the list.
700 Mandatory field {0} is missing
701 There can be a maximum of 64 contact fields.
702 Number {0} must either be either 10 digits for dialing within North
America or begin with 011 for dialing outside North America.
703 Number {0} has to be less than or equal to 16 digits and greater than
or equal to 10 digits.
704 No match found for list domain that was entered.
706 At least one number should be specified for new record.
707 No value provided for key {0}.
708 More than one record matches specified criteria.
709 At least one key must be provided.
710 Time format must be provided along with Time to Dial.
711 Incorrect Time to Dial.
712 Incorrect key {0}. No such field.
713 Value of field {0} is too long.
Codes Description
Result Codes
23 Web2Campaign • Developer’s and Administrator’s Guide
714 Value of field {0} has incorrect format.
715 Number of requests exceed the maximum allowed value: {0}.
716 The requested domain is disabled.
717 There are no resources for processing the request. The maximum
allowed number of concurrent requests: {0}. Please try to re-send the
request.
719 Incorrect country code {0}. Country code is string contains 2 letters.
720 The {0} country code is not found.
System Errors
800 Error while executing request.
801 Unknown error. Illegal pattern character {0}
804 Error while processing CallASAP and Time to call parameters. The
service is temporarily unavailable.
805 Error while loading external parameters.
Codes Description

Navigation menu