Import contacts in bulk

Third parties use the Bulk Contact Import APIs to merge and insert metadata and recordings in a multi-part HTTPS request.

There are two Bulk Import APIs:

• Bulk Contact Import API—Used by third parties; allows insertion of both metadata and recordings in a multi-part HTTPS request

  NOTE   You can also use the Bulk Contact Import API to import contacts in bulk through the Data Server. See Using the Data Server for bulk contact import.

• Real-time Contact API—Used by Workforce Optimization Smart Desktop recording client; inserts metadata first and then uploads recordings separately later, based on the response from the metadata insertion. This allows the client to delay uploading recordings and allows contacts to be inserted while the call is still in progress. However, this forces the client to track IDs to upload the recordings for the correct contact.

Protocol and URI

Bulk contact import API

Real-time bulk contact import API (metadata)

Supported formats

The following formats can be included in a multipart request.

Request and response fields

The CSV and JSON files include fields defined in the following table. Not all fields are used in both types of files. The file the field applies to is indicated in the description.

CSV file examples

CSV can be uploaded as part of a multipart upload request. Some rules regarding the format are as follows.

• The number of columns is variable. For example, if you always want to use the customer’s time zone, you do not have to include the TimeZone column in the CSV.
• The columns included in the CSV can be in any order.
• The number of columns in each row must match the number of header columns.
• If a value has a comma, it must be surrounded by quotes.

• If a value is not known for a specific contact, but the header exists, use a empty string for that column.

  NOTE   A successful response is formatted in JSON, because the response adds some status for each contact and recording.

Full example

This example shows a file that uses every field possible for a CSV file.

1
2
3
AgentId,ContactStartTimeMs,TimeZone,AssocCallId,CallId,CalledAddress,Line,CallingAddress,Direction,Recording1,Recording2,Recording2Offset,metadata.accountNumber
abc/bunkowm,1447100000000,America/Chicago,103585664793210000,30611848,1801,1800,1800,1,call1.webmv,call1.wav,5000,1234567890
mark.bunkowske@abc.com,1447110000000,America/Chicago,103585664793220000,30611848,1801,1800,1800,1,call2.wav,,,987654321

Short example

This example shows only the fields required for a CSV file.

1
2
3
AgentId,ContactStartTimeMs,Recording1
2,1447100000000,call1.wav
2,1447110000000,call2.wav

JSON file examples

Contact information can be imported into Workforce Optimization in JSON format as an alternative to CSV format.

Full Example

The following is an example of a formatted JSON file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
   "AgentId":"john.smith@acme.com",
   "AssocCallId":"103585664793254280",
   "CallId":"30611848",
   "CalledAddress":"1801",
   "CallingAddress":"1800",
   "ClientTimeZone":"Central Standard Time",
   "ContactStartTimeMs":1447075073000,
   "Direction":1,
   "Audio":[
      {
         "Location":"25.wav",
         "StartTimeMs":1447075080000
      }
   ],
   "Screen":[
         "Location":"25.webm",
         "StartTimeMs":1447075075000
   ],
   "CustomMetadata":{
         "accountNumber":"123456",
         "department":"sales"
    }
}

Short example

This example shows only the fields required for a JSON file.

1
2
3
4
5
6
7
8
9
{
   "AgentId":"acme\smithj",
   "ContactStartTimeMs":1447075073000,
   "Audio":[
      {
         "Location":"25.wav"
      }
   ]
}

ZIP format

The ZIP format is handled differently than CSV or JSON, in that it is a collection of files that are processed as if they were individual files within the multipart request.

• The name of the file is the key that needs to be referenced in the CSV/JSON.
• Any folder structure in the ZIP file is flattened and ignored.

For example, a multipart request looks like the following.

1
2
3
4
batch.zip
   batch.csv (contains 2 rows, for call1 and call2)
   call1.wav
   call2.wav

This multipart request is processed as if the files were all in the ZIP or all individually in the multipart request.

Notes

• The order of files does not matter.
• An upload for a contact that contains a recording file name but does not include that recording will fail to be inserted.
• An upload that contains a recording the is not referenced in a CSV or JSON will ignore that recording.

IMPORTANT   You must have Tenant Administrator access, access to the data server to use for the Bulk Contact Import, and the Bulk Import permission checked for your role.

Using the Data Server for bulk contact import

You can use the Bulk Contact Import API to upload contacts in bulk through the Data Server.

Using the Bulk Contact Import API requires the following:

• Workforce Optimization Administrator role with the Bulk Import permission enabled.
• Read/write access to the Data Server.

To upload contacts in bulk through the Data Server:

PREREQUISITE   For a bulk import to successfully upload files using a data server, the data server must be configured within Workforce Optimization. This can be a Data Server that is already being used for any other purpose or a new Data Server. If you are configuring a new Data Server for bulk import, see the topic, “Data Server Configuration” in the Workforce Optimization User Guide.

1. To use a data server that is already configured in Workforce Optimization navigate to the Data Server Configuration page (Application Management > System Configuration > Data Server Configuration) and select that data server.
2. In the Regional Data Server ACD Sync Settings section, ensure that Enable Capture is selected and that the Generic (Default) ACD is assigned.
3. Click Save.
4. Create a CSV (not JSON) file that contains all required fields, plus any optional ones that you want to add.

5. Prefix the file with the word CONTACT. The word is case-sensitive, and you must type it in upper-case.

   EXAMPLE   

   Your CSV file is named ExampleContacts.csv. You must rename it with the CONTACT prefix as follows:

   CONTACT.ExampleContacts.csv

6. Place the CSV file and all associated media files in the GIS <tenant> folder on the Data Server. This folder is in the location defined by the Regional Data Server GIS File Location field on the Data Server Configuration page.

   EXAMPLE   C:\Program Files\Common Files\Workforce Optimization\Data Server\gis\<tenant>