Adding/Appending Records to Active Campaigns (U10)

Return to User Hub

Introduction

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

Requirements and Limitations

• You must be on platform release v.5+ and utilize the platform’s campaign APIs to use campaign appending.
• Only Sysadmin, Superuser, and Manager user role types have access to campaign appends. 
  
• 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. This allows appended campaign records to be handled with priority over existing campaign records.  
• Requeue campaigns do not support append functionality.
• The 'Append Campaign Record' API method only works on campaigns that have the Allow Append option enabled.
• 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.
• Campaign ID is required to use this functionality. The Campaign ID can be retrieved from the campaign upload process, but the campaign must be built for the API to append records.
• You can also get the Campaign ID by recording the Campaign ID number from the portal. 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 regarding the ‘Find Matching Campaigns’ and ‘Append Campaign Record’ API.

The Developer Portal is available from the Resources drop-down menu in the voice 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).
• No more than 10 phone numbers per record are appended.
• 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.
• Campaigns that can be appended follow the configured dialing sort rules set at the service level and are restored 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 the last record to the first record for dialing purposes. 
• Appends does 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 voice portal. To enable campaign appending, follow the procedure below:

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

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 User Guide on User Hub.

   Allow Append checkbox
   

2. Click Upload to upload the campaign file.

Campaign files with campaign append allowed display a green checkmark in the Allows Append column in 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.

This is also viewable in the Campaign details screen. This attribute is displayed as read-only.

Append Campaigns Report at End of Day

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

• If enabled, campaigns that have append enabled report at the end of the day.
• If disabled, campaigns report when out of dialable records which would prevent records from being appended from that point when the Campaign is stopped.

Appending Records to Active Campaigns

Appending records to active campaigns uses the Append Campaign Record API method. For further information on using LiveVox API's refer to the Developer Portal link from the voice portal. Having uploaded a campaign, as described previously in this document, follow these steps to append new records to campaigns. 

Establish User Session

The first step required is to establish a user session with the LiveVox platform. The session API is necessary because it returns a 'session Id' which must be passed with every subsequent API call. The session API requires three elements to login – 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 take and receive calls.  For this section, a user account is used.  To determine if you are using a user or agent account, simple try to log into the LiveVox Portal.  If you can login to the LiveVox portal, you can login to the LiveVox APIs as a user. If you are unable to login to the LVP contact support@livevox.com for help in troubleshooting the issue.

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

Find the Campaign ID

You can locate the Campaign ID by using the Find Matching Campaigns API. Prior to using the Find Matching Campaigns API, the campaign must have a Campaign ID on the platform. This is achieved by first 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.

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

Search for campaigns for client id limited to only 10 records at a time. Specified the date 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 a third-party site, https://currentmillis.com to aide 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 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 the code snippet.

Append Record to Campaign

Once the Campaign ID has been obtained, the next step is to append a record to the campaign. Along with the LV-Session token, the Campaign ID must be included as a URL parameter in the HTTP PUT request along with a simple record containing 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.

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 the code snippet.

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

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 can view a new record, including newly added phone numbers on the Phone 2 column.