Voxjar logo

How Can We Help?

How to Integrate AWS S3 with Voxjar

Voxjar's integration with AWS S3 lets you create a connection, verify access, and map the metadata between your S3 buckets and Voxjar.

The connection allows Voxjar to download call recordings and metadata from your storage on a schedule or when manually triggered.

You can create multiple connections by creating multiple integrations.

To create a new S3 integration, go to Settings>Integrations (app.voxjar.com/settings/integrations) and click on AWS S3.

aws s3 integration screenshot

Connecting Your Bucket

aws s3 call recording integration connect modal

You'll need the name of the bucket where you store call recordings (don't enter the url, just the bucket name) and credentials to access the bucket.

The credentials must have permissions to list and download files from the bucket you've assigned.

To generate credentials, create a new user in AWS with the required permissions and download the new user's credentials.

Name this integration so you can identify it later; enter your bucket name, region, and credentials; and click "check access". 

Your bucket must contains files to complete the connection tests. Voxjar has to verify that it can read and download those files.

Set your Audio Path

s3 file path & metadata options

After your connection has been tested, you'll need to provide the path to your audio files. 

There are two supported conventions.

  1. Send all files to the path you provide with no subfolders eg. my_path/my_audio_file.wav
  2. Create date subfolders formatted as YYYY/MM/DD eg. my_path/2023/01/04/my_audio_file.wav

Option 2 is preferred if you do not purge your data on a regular interval. Otherwise the data build up could prevent Voxjar from completing a data pull within our 1 hour time limit.

Metadata Sources

Metadata lets Voxjar label your call recordings with standard and custom fields. This is useful for filtering results, identifying specific calls, linking calls to agents, and selecting which call recordings should be evaluated.

There are three options for AWS S3:

  1. Parse metadata from the audio file name eg. call-id_agent-id_timestamp.wav
  2. Extract metadata from a single CSV file
  3. Extract metadata from JSON files (1 per audio file)

For CSV and JSON file paths there are two supported conventions. The same as with audio file paths.

  1. Send all files to the path you provide with no subfolders eg. my_path/my_metadata_file.csv
  2. Create date subfolders formatted as YYYY/MM/DD eg. my_path/2023/01/04/my_metadata_file.json

Option 2 is preferred if you do not purge your data on a regular interval. Otherwise the data build up could prevent Voxjar from completing a data pull within our 1 hour time limit.

Parse Audio File Name Metadata

Parsing metadata from your call recording file names is the simplest way to start if you don't have detailed metadata files.

Voxjar will extract metadata from your file names based on rules you set in the next step.

CSV Metadata File

s3 call recording metadata from csv file

If you save your metadata in a CSV file you can provide the path to those files the same way you provide a path to your audio files.

Only 1 CSV file will be downloaded on every data collection run. That means that if you schedule data to be pulled every 7 days, all metadata for that 7 day period needs to be stored in a single CSV file.

Each row in a CSV metadata file should represent 1 call.

Voxjar will only download calls that are included in your CSV file and that match the rules you set in your Queues.

Your CSV file must contain a column that references the call recording's file name so Voxjar can link the data to the call. You do not need to provide the full call recording path in the CSV file since you have already provided that. Just the file name.

During set up, make sure that there is at least 1 CSV file with data at the path your provide so you can map your columns to metadata fields in Voxjar.

Any changes to your CSV columns could break this integration. When you make changes you will need to create a new integration and map the new metadata fields.

JSON Metadata Files

If you save your metadata as JSON files you can provide the path to those files the same way you provide a path to your audio files.

Each JSON metadata file should represent 1 call.

Voxjar will only download calls that have a matching JSON file and that match the rules you set in your Queues.

Your JSON file must contain a field that references the call recording's file name so Voxjar can link the data to the call. You do not need to provide the full call recording path in the JSON file since you have already provided that. Just the file name.

During set up, make sure that there is at least 1 JSON file with data at the path your provide so you can map your fields to metadata fields in Voxjar.

Any changes to your JSON fields could break this integration. When you make changes you will need to create a new integration and map the new metadata fields.

s3 call recording metadata from json file

Map your Metadata

Metadata lets Voxjar label your call recordings with standard and custom fields. This is useful for filtering results, identifying specific calls, linking calls to agents, and selecting which call recordings should be evaluated.

There are three options for AWS S3:

  1. Parse metadata from the audio file name eg. call-id_agent-id_timestamp.wav
  2. Extract metadata from a single CSV file
  3. Extract metadata from JSON files (1 per audio file)

Parse Audio File Name Metadata

Call recordings will often contain metadata in their file names. You can tell Voxjar how to parse that data and assign some of it to specific metadata fields in Voxjar.

Each field will need to be separated by the same delimiter. That delimiter should not be used anywhere else in the file name or Voxjar will not be able to successfully parse the call recording file names.

Custom metadata is not supported for file name parsing.

The supported fields are:

  • Call Identifier
  • Call Timestamp
  • AgentId
  • AgentName
  • CustomerId
  • CustomerName
  • CustomerPhone
select delimiter and metadata fields for AWS S3 call recording in Voxjar

CSV/JSON File Mappings

Voxjar will parse as many CSV columns or JSON fields as it can from your provided files to give you flexibility in labelling your calls.

You can assign each one to a Standard or Custom Voxjar metadata field.

Custom metadata mapping uses the field or column name as the label in Voxjar and requires that you select a data type so Voxjar can treat it correctly.

Currently, only the String/Text type custom fields are used to filter your Queues. 

Supported data types are:

  • String/Text
  • Number (whole numbers)
  • Boolean (true/false)
  • Duration 
  • Percent (decimals)
  • DateTime

The standard Voxjar fields are:

  • AudioFileName - This is the only required mapping
  • Transcript - (how to bring your own transcripts)
  • Call Identifier
  • Call Timestamp
  • AgentId
  • AgentName
  • CustomerId
  • CustomerName
  • CustomerPhone
JSON metadata mapping for call recordings on AWS S3 to Voxjar