This document provides an overview of the LiveVox Adding/Appending Records to Active Campaigns 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.

Features

The Append functionality contains the following features:

  • Records can only be appended to "today's” campaigns. 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 on campaigns that have the Allow Append option enabled.
  • You can append new records 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 during the campaign upload process or by using one of the following API methods:
    - Find Matching Campaigns
    - List Campaigns
    For more information, see Search the Campaign ID. It is recommended that you use one of the above 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 Find Matching Campaigns, List Campaigns, and Append Campaign Record API sections in Campaign API documentation.
  • For appended records, the related Campaign name is displayed in standard reports including the Account Lookup Report and Phone Lookup Report within the LiveVox portal.

Special Considerations

  • It is recommended that you append records every 20 seconds (API must not be called more than 5 times per rolling minute).
  • Up to 30 phone numbers can be appended per record.
  • The Campaign build functionality applies only to the initial build but not to the appended records. Tasks such as cell phone scrub or duplicate number checking are not performed on the appended records.
  • API method requires only Phone_1 (or 1 phone number) at a minimum to append the records.
  • Appends are limited to a maximum of 10,000 records per API call.
  • Normally uploaded campaign records will follow the configured dialing sort rules set at the service level.
  • All appended records to the target campaign are handled with priority (by default) with a first in first out method.

  • Appended records follow DNC and dialing profile restrictions.

  • Campaign Appends do not apply to the following Campaign Types:
    • CALLBACK
    • INBOUND
    • SCHEDULED_CALLBACK
    • MANUAL

Append Campaign Functionality

Enable Campaign Appends 

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

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

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.

    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 Admin Guides on Product Documentation.

  2. Click Upload to upload the campaign file.

If you enable the Allow Append feature for a Campaign, the campaign displays a green checkmark in the Allows Append column of the Campaigns section. You must enable the Allow Append column view through the Customize Campaigns Grid configuration option as this is not visible in the default Campaigns view.

The Allow Append option is also viewable in the Campaign details screen but cannot be modified.

Append Campaigns Report at End of Day

The Services section displays the Append Campaigns Report at End of Day in the Settings tab.

  • If enabled, append enabled campaigns to generate a report at the end of the day.  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. Once a campaign is in the Done or Reported status, no additional records can be appended to the campaign.

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.

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. 

Users can access the LVP https://login.livevox.com, which allows them to perform administrative tasks on the platform. If you are unable to log in to the LVP, contact customercare@livevox.com for help in troubleshooting the issue.

Only Sysadmin, Superuser, and Manager user role types can append records.

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

2. Search the Campaign ID

Before using the Append Campaign Records API, the campaign must have a Campaign ID on the platform. You can add the campaign 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.  

Alternately, the Campaign ID can be retrieved using the Find Matching Campaigns or List Campaigns API methods as explained below.

Find Matching Campaigns API Method

To locate the appropriate Campaign ID using the Find Matching Campaigns API perform a search against the Service ID associated with the target campaign. You can also supply the expected campaign state and type when searching as well. This provides the Campaign ID to use in subsequent append requests to that campaign.

Specify the date range with a 15-minute interval in the "from" and "to" element.  The "from" and "to" values are in milliseconds since Epoch uses a third-party site, https://currentmillis.com, to 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. The "type" is set to a "1" for Outbound.

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

Search for campaigns for client id limited to 1000 records at a time.

List Campaigns API Method

This method provides the list of loaded campaigns for a client. To locate the appropriate Campaign ID using the List Campaigns API, you can specify the number of items to return in the list (count) and start listing from the count (offset). This provides the Campaign ID to use in subsequent append requests to that campaign.

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

Search for campaign ID limited to 1000 records at a time.

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 token, 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. 

  • As a best practice, it is beneficial to append records with "phone1" and the "account" for screen pop and reporting purposes. Additional properties can be added as needed to further identify the appended records.
  • The "practicePhoneAlternate" is an optional property and it is the best practice to include this property in the request. If the "practicePhoneAlternate" property is not included in the request then the caller ID will be null.

You can 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 an example of the Request and Response.

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

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.

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 fields 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.

Loaded and Uploaded values are updated regardless of whether the campaign is playing or not.

LiveVox Customer Care Contacts

24 Hour Customer Care Line: (888) 477-3448
LiveVox Customer Care Email: customercare@livevox.com
This document is an unpublished work protected by the United States copyright laws and is proprietary to LiveVox, Inc. (“LiveVox”).  Disclosure, copying, reproduction, merger, translation, modification, enhancement, or use by anyone other than authorized employees, clients or licensees of LiveVox, and its affiliate companies, without the prior written consent of LiveVox, is prohibited.  This document is intended as a guide to assist users of systems provided by LiveVox, and does not constitute the provision by LiveVox of any legal or compliance advice.  Compliance by authorized clients or licensees of LiveVox with any and all applicable local, state, federal, or foreign laws and regulations is the sole responsibility of those authorized clients or licensees.  Further, features and services that rely on third Party performance are subject to the errors and omissions of those third Parties, over which LiveVox has no control.  LiveVox therefore disclaims any and all liability resulting from or arising out of any services supplied by or through any third Party vendor or any acts or omissions of the applicable third Party vendor.  Additionally, LiveVox makes no representations or warranties with respect to the accuracy of content supplied by Parties other than LiveVox.


 

For Internal and Client Use only