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 Calabrio ONE 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

URI /api/upload/contacts
Method POST
Permissions Administer Tenant
Content Type multipart/form-data

Real-time bulk contact import API (metadata)

URI /api/rest/wfo/contact/import
Method POST
Permissions Record Voice/Record Screen
Content Type application/JSON

Supported formats

The following formats can be included in a multipart request.

Type Description
CSV A comma-separated file used to assign metadata.
JSON The same metadata format as the Real-time API, but can be used for bulk import.
WAV An audio recording format.
WEBM A combined audio and video recording format.
WEBMA An audio-only (WebM container) format.
WEBMV A video-only (WebM container) format.
SPX An audio format.
WMV A combined audio and video recording format (or video only if paired with audio in the same contact).
OPUS An audio format.

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.

Name Req? Description
AgentId

Y

Used in CSV and JSON.

The Agent ID in one of three formats. Processing figures out which format is used based on parsing the contents.

  • Person ID. A unique identifier from WfoPerson.id. This number is also used in the User Export spreadsheet (Application Management > Global > Users > Import and Export > Export > User ID column). It is not the same as the ID in the Calabrio ONE user profile.
  • AD Login. A domain\username (requires “\”).
  • Email address. An email address (requires “@”).

When using a CSV to upload contacts, the agent ID is required. If you are using JSON to make the request, the agent ID is optional. In the latter case, the agent ID is set to the ID of the authenticated user initiating the upload.

Max characters = 254
Default = none

AssocCallId

N

Used in CSV and JSON.

An ID that ties contacts together. For example, a transferred call from one agent to another each have the same ID.

Max characters = 52
Default = NULL

Audio.Location

N

Used in CSV and JSON.

In the Audio sub-object. The key (file) name of the recording in the multipart request. This can be any supported recording format (audio/screen/combined). Only a single audio file per contact is allowed. The key name must have a valid extension that matches the media type of the recording. The extension identifies the file as an audio or screen recording, or both.

Max characters = 128
Default = None

Audio.StartTimeMs

N

Used in CSV and JSON.

In the Audio sub-object. The start time in milliseconds GMT since 1970-01-01 (UNIX time) of the audio recording. This is used to determine the audio offset from when the contact starts.

Max characters = long
Default = ContactStartTimeMs

CalledAddress N

Used in CSV.

The called phone number.

Max characters = 64
Default = Empty string

Called

N

Used in JSON.

The called phone number.

Max characters = 64
Default = NULL

CallId

N

Used in CSV and JSON.

An ID that identifies a contact.

Max characters = 128
Default = NULL

Calling

N

Used in JSON.

The calling phone number.

Max characters = 64
Default = NULL

CallingAddress

N

Used in CSV.

The calling phone number.

Max characters = 64
Default = Empty string

ClientTimeZone

N

Used in CSV and JSON.

The time zone in UTC format. Windows Time is also supported. The Desktop Recording client sends Windows Time, which is mapped to Olson time.

Max characters = 255
Default = Customer’s time zone as defined in Calabrio ONE

EXAMPLE    –06:00

ContactStartTimeMs

N

Used in CSV and JSON.

The start time in milliseconds GMT since 1970-01-01 (UNIX time). A value in this field is required, so if the value is missing, the API uses the current upload time. Note that this likely results in a poor user experience, with many contacts that have the same timestamp.

IMPORTANT   If you are importing contacts with Excel, you must format the Start Time column to display milliseconds (consult the Excel user documentation for more information). Otherwise, Excel truncates milliseconds, resulting in a false time and preventing recordings from importing correctly.

Max characters = long
Default = current upload time

EXAMPLE   1447100000000 - 11/09/2015 20:13:20 GMT

Direction

N

Used in CSV and JSON.

The direction of the call, inbound or outbound.

0 = outbound
1 = inbound

Max characters = 1
Default = NULL

Line

N

Used in CSV and JSON.

The agent’s line/extension.

Max characters = 64
Default = NULL

metadata.<custom metadata field name>

N

Used in CSV.

The custom metadata fields to populate. The field will be created if it does not exist. Any column beginning with “metadata” will be treated as a custom metadata field.

EXAMPLE   To set “accountNumber”, create a column named “metadata.accountNumber”.

Max characters field name = 39
Max characters of custom metadata value = 2056

CustomMetadata

N

Used in JSON.

The custom metadata fields to populate. The field will be created if it does not exist. The object contains data in the form of name/value pairs.

EXAMPLE    “accountNumber”:”123456”

Max characters field name = 39
Max characters of custom metadata value = 2056

Recording1 Y

Used in CSV.

The key (file) name of the recording in the multipart request. This can be any supported recording format (audio/screen/combined). Only a single audio file per contact is allowed. The key name must have a valid extension that matches the media type of the recording. The extension identifies the file as an audio or screen recording, or both.

Max characters = 128
Default = None

Recording2 N

Used in CSV.

The key (file) name of the recording in the multipart request. This can be any supported recording format (audio/screen/combined). Only a single audio file per contact is allowed. The key name must have a valid extension that matches the media type of the recording. The extension identifies the file as an audio or screen recording, or both.

Max characters = 128
Default = None

Recording3 N

Used in CSV.

The key (file) name of the recording in the multipart request. This can be any supported recording format (audio/screen/combined). Only a single audio file per contact is allowed. The key name must have a valid extension that matches the media type of the recording. The extension identifies the file as an audio or screen recording, or both.

NOTE   There must be an audio file or the import fails.

Max characters = 128
Default = None

Recording2Offset N

Used in CSV.

The offset of Recording2 from Recording1.

EXAMPLE   An audio file (WAV) that starts 5 seconds after the screen file (WEBM) has an offset of 5000 (5000 = 5 seconds).

Max characters = Long
Default = 0

Screen.Location

N

Used in CSV and JSON.

In the Screen sub-object. The key (file) name of the recording in the multipart request. This can be any supported recording format (audio/screen/combined). Only a single audio file per contact is allowed. The key name must have a valid extension that matches the media type of the recording. The extension identifies the file as an audio or screen recording, or both.

Max characters = 128
Default = None

Screen.StartTimeMs

N

Used in CSV and JSON.

In the Screen sub-object. The start time in milliseconds GMT since 1970-01-01 (UNIX time) of the screen recording. This is used to figure out the screen offset from when the contact starts.

Max characters = long
Default = ContactStartTimeMs

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.

Copy
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
[email protected],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.

Copy
AgentId,ContactStartTimeMs,Recording1
2,1447100000000,call1.wav
2,1447110000000,call2.wav

JSON file examples

Contact information can be imported into Calabrio ONE in JSON format as an alternative to CSV format.

Full Example

The following is an example of a formatted JSON file.

Copy
{
   "AgentId":"[email protected]",
   "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.

Copy
{
   "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.

Copy
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:

  • Calabrio ONE 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 Calabrio ONE. 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 Calabrio ONE User Guide.

  1. To use a data server that is already configured in Calabrio ONE navigate to the Data Server Configuration page (Application Management > System Configuration > Data Server Configuration) and select that data server.

  2. Ensure the following features are enabled:

    • In the Regional Data Server ACD Sync Settings section, select Enable Sync and assign the Generic (Default) ACD.
    • In the Regional Data Server ACD Sync Settings section, select Enable Capture and assign the Generic (Default) ACD.
    • In the Regional Data Server ACD Sync Settings section, select the Enable Media Import check box and assign the Generic (Default) ACD.
  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\Calabrio ONE\Data Server\gis\<tenant>