Introduction

This document provides an overview of the LiveVox Adding/Appending Records to Active Campaigns features.

Important Information

Requirements

Features

The Append Campaign Record APIs are supported on all GA (General Availability) releases of the platform. Only Sysadmin, Superuser, and Manager user role types have access to campaign appends. Requeue campaigns do not support append functionality.

The Append functionality contains the following features:

• Records
• Client must be on platform release v.5+ and utilize this platform’s campaign APIs to use this functionality.
• The records can only be appended to "today's” campaigns.    
• Requeue campaigns do not support append functionality.
• Enhanced campaign append functionality which allows the service level dialing sort to be superseded for priority record handling is available as of LiveVox U10. This allows appended campaign records to be handled with priority over existing campaign records.
• The 'Append Campaign Record' API method only works The API calls will only work on campaigns that have the 'Allow Append' option enabled. To use the 'Allow Append', the client must first have the 'Campaign Appends Allowed' checkbox enabled (Client->Settings). This document covers specific configuration details. option enabled.
• You can append new records New records can be appended to active campaigns only in Built, Pause, or Play status. New transactions appended to campaigns in the Stop status are not supported.
• The target Campaign ID is required to use this functionality. The Campaign ID can be retrieved from during the campaign upload process , but the campaign must be built for the API to append records. It is suggested to or by using the 'Find Matching Campaigns' API method. For more information, see Find the Campaign ID.

It is recommended that you use the 'FindMatchingCampaigns' API method to gather the Campaign ID and then use that information to insert the Campaign ID into the

Append Campaign Record API call. For more information, see the User Hub’s Developer Portal

under the Campaign API documentation section

on Find Matching Campaigns and Append Campaign Record API.

The Developer

Portal is available from the Resources

drop-down menu

of the voice portal:

Figure 1: Developer portal link

• Another way to get the Campaign ID is to record the Campaign ID number from the portal. See Find the Campaign ID for further information.

Special considerations

Image Added

Special Considerations

• It is recommended that you append records It is suggested to append records as frequently as every 20 seconds (in other words, the API should must not be called more than 5 times per rolling minute).
• No more than 10 Up to 30 phone numbers can be appended per record are appended.
• The Campaign build functionality does not apply applies only to the initial build but not to the appended records, only to the initial build. With this, no . Tasks such as cell phone scrub or duplicate number checking , for example are not performed on the appended records.
• API method requires only Phone_1 (or 1 phone number) at a minimum to append the records.
• There is Appends are limited to a maximum of 10,000 records allowed per API call.
• Campaigns which can be appended Normally uploaded campaign records will follow the configured dialing sort rules set at the service level and will be resorted after each successful append request.
• Set the service’s dialing sort to, “Inverted Consecutive” to dial the newly appended records at the next opportunity. This dialing sort uses the order in which records are loaded, from last record to first record for dialing purposes. 
• .
• All appended records to the target campaign are handled with priority (by default) with a first in first out method.
• Campaign Appends do not apply to the following Campaign TypesCampaign Types this functionality does NOT pertain to:
  • CALLBACK
  • INBOUND
  • SCHEDULED_CALLBACK
  • MANUAL

Append Campaign Functionality

Campaign Appends Allowed - Client Editor Settings

The Client editor displays Campaign Appends Allowed in the Settings tab. When unchecked, the campaign level attribute will not be available in the campaign upload screen. When checked, the campaign level attribute is configurable.

Figure 7: Campaign Appends Allowed in Client editor

Allow Append - Upload Campaign

To allow append, the user should select Upload from the Campaigns section or the Campaigns panel.  The upload campaign screen displays an Allow Append checkbox which allows the campaign file to be appended to an active campaign.[1]

Figure 8: Allow Append checkbox

Anchor
eca eca

Enable Campaign Appends 

You can enable Campaign Appends in the Client section of the voice portal by following the procedure below:

1. Navigate to Configure > Client/Service > Client > Settings tab.
2. Click Campaign Appends Allowed in the Advanced Features section.
   Image Added
   

Anchor
aca aca

Allow Append Campaigns

To allow appending on a campaign, follow the procedure below:

1. When uploading a campaign, click the Allow Append option from the Advanced tab. This allows campaign records to be appended to the active campaign.
   

   Note
   You can find the Upload a file option by navigating to Configure > Campaigns > Campaigns from the navigation panel. Detailed instructions on uploading a campaign and assigning dialing characteristics are available in the User Guide on User Hub.

   Image Added

2. Click Upload to upload the campaign file.

If you enable the Allow Append feature for a Campaign, the campaign displays Campaign files with campaign append allowed display a green checkmark in the Allows Append column in of the Campaigns editorsection.    You You must enable the “Allow Append” Allow Append column view through the Customize Campaigns Grid configuration option as this is not visible in the default Campaigns view.Figure 9:

Image Added

The Allow Append columnThis option is also viewable in the Campaign details screen .  This attribute is displayed as read only.Figure 10: Allow Append option read onlybut cannot be modified.

Image Added

Anchor
acred acred

Append Campaigns Report at End of Day

The Services editor section displays the Append Campaigns Report at End of Day in the Settings tab. When checked, campaigns that have append enabled will

• If enabled, append enabled campaigns to generate a report at the end of the day.

When unchecked

•   This allows additional records to be appended even if no dialable records are remaining in the campaign.
  
• If disabled, campaigns will report when they run out of dialable records

which would prevent records from being appended from that point when the Campaign is stopped.

• . Once a campaign is in the Done or Reported status, no additional records can be appended to the campaign.

Image Added

Appending Records to Active Campaigns

Appending records to active campaigns uses the Append Campaign Record API method. For more information on using LiveVox APIs, see the Developer Portal. Follow the procedure below to append new records to campaigns.

Anchor
eus eus

1. Establish User Session

To append records, you must establish an API user session with the LiveVox platform. This is required because it returns a 'session Id' which must be passed with every subsequent API call. The session API requires three elements to log in – client name, username, and password. The session API accepts both User and Agent credentials.

User accounts can access the LiveVox voice portal (LVP) https://login.livevox.com, which allows them to perform administrative tasks on the platform. Agent accounts are used to log into the ACD to make and receive calls. For this section, a user account is required. To determine if you are using a user or agent account, log in to the LiveVox Portal. If you can log in to the LiveVox portal, you can log in to the LiveVox APIs as a user. If you are unable to log in to the LiveVox Platform, contact customercare@livevox.com for help in troubleshooting the issue.

Once the API request is made, a response containing the 'session id' and the client id to be used in subsequent requests is returned.

Anchor
fci fci

2. Find the Campaign ID

Before

Figure 11: Append Campaign Report at End of Day in Services editor

Appending a new campaign file

Upload a campaign file

Note : Detailed instructions on uploading a campaign and assigning dialing characteristics are available in the User Guide on User Hub. The upload a file option is available once navigated to the Campaigns section by electing Configure > Campaigns > Campaigns from the Navigation Panel.

Figure 12: Uploading a campaign file with Allow Append

Find the Campaign ID

Locating the Campaign ID to be used for the Append Campaign API is a key step.  The Find Matching Campaigns API is available for this.  Please note, that prior to using the Find Matching Campaigns API, the campaign must first have a Campaign ID in on the platform.   This is achieved by first You can generate a Campaign ID by loading the initial file into the platform. Once the file is loaded, the Campaign ID is generated as shown below on the General tab of the Campaign details.

Figure 13: Sample Campaign ID and Service ID displayed in Campaign Details

  Alternately, the Campaign ID can be retrieved using the 'Find Matching Campaigns' API method.

Image Added

To A typical way to locate the appropriate Campaign ID is to load the initial file at a certain time of day and then use using the Find Matching Campaigns API to perform a search by against the time and Service ID associated with the target campaign.   You may can also supply the expected campaign state and type when searching as well.   This will provide provides the Campaign ID to use in subsequent append requests to that campaign.

Figure 14: Find Matching Campaign ID request

Set the "LV-Access" token to the LiveVox supplied token and the "LV-Session" token to the session id retrieved from the Session Login API.  Search for campaigns for client id limited to only 10 records at a time.   Specified Specify the date Range range with a 15-minute interval in the "from" and "to" element.  The "from" and "to" values are in number of milliseconds since Epoch and use uses a third-party site, https://currentmillis.com, to aide aid in generating the values.   The "state" element is set to match the possible states we expect the campaign to be in when performing the search.   The "service" element contains the Service ID that the campaign is configured for in the platform (See Figure 13).   The "type" is set to a "1" for Outbound.

From the Response, we should receive the Campaign ID in the "campaign" array under the "id" element.   This id ID is to be used for the append operation. The following is an example of the Request and Response.

Figure 15: Campaign ID

Append Record to Campaign

Image Added

Anchor
arc arc

3. Append Records to a Campaign

After you generate the Campaign ID, you can append records to the target campaign. In addition to the LV-Session API tokenOnce the Campaign ID has been obtained, the next step is to append a record to the campaign.  Along with the typical inputs of the "LV-Access" and "LV-Session" tokens, the Campaign ID must be included as a URL parameter in the HTTP PUT request along with a simple record containing (at minimum) a phone number.   Only the "phone1" element is required by the Append Record to Campaign API, but additional information such as account number, names, email, etc. can be submitted in a real-world scenario.

Figure 16: Append campaigns example request

. 

You can You may enter additional phone numbers using the phone2 field. This should be entered as an array of phone numbers.   This field can be filled with up to 30 additional phone numbers separated by a comma.   In this example, two additional phone numbers are added to the appended record.   The following is the code in JSON for the phone2 field.an example of the Request and Response.

Image AddedFigure 17: phone2 field

After submitting the append request, a Status status code of 204 should be returned indicating the record has been successfully added to the campaign.

Figure 18: Successfully appended campaign message

Anchor
var var

4. View

Appended Records

To view your appended records on the selected campaign, navigate to the Campaign details screen and select the Campaign Records tab.  You will be able to view a new record, including newly added phone numbers on the Phone 2 column.

Figure 19: Appended record in Campaign Details screen

Image Added

Real-Time Statistics for Appended Campaign

Real-time campaign statistics are updated to reflect the appended campaign records within the LiveVox Portal. The below list provides the cumulative list of all the fileds on the various  campaign monitor panels. Each configured campaign monitor panel will display only the relevant fields applicable to it. 

• Uploaded: Number of records uploaded in original campaign and all records appended in the campaign
• Loaded: Number of valid records in original campaign and all records appended in the campaign
  
• Completed: Number of dialed records
• Remaining: Number of records yet to be dialed
• % Completed: The percentage of records that have completed dialing.
• Total: Total number of valid records in the original campaign and all records that are appended in the campaign.
  
• % Done: The percentage of records that have completed dialing.