Restrictions

All metadata uploaded to V‑Spark has the following restrictions:

  • All metadata field names are case-insensitive, including reserved and custom field names. For example, AgentID, agentid, and AGENTID are equivalent metadata field names.
  • Custom metadata values and field names may be composed of any valid Unicode characters, except for the reserved non-alphanumeric characters : (colon, Unicode 003A) and = (equals sign, Unicode 003D).
  • If you upload metadata via XML rather than JSON, your metadata field names cannot contain spaces. Metadata values can contain spaces in both XML and JSON.
Note:
As a best practice, do not preface custom metadata field names with =, +, -, or @. These characters may cause unexpected system behavior:
  • Field names prefaced with + or - are not included in search results.
  • Field names beginning with =, +, -, or @ are prefaced with an apostrophe ' in CSV exports to prevent spreadsheet applications from interpreting such labels as formulas.

Reserved fields

The following field names are reserved for V‑Spark functions. Key values for these fields may be submitted as metadata, but they cannot be configured as custom metadata fields for folders.

  • _all

  • _id

  • agent

  • agent id

  • agent_v3

  • agentid

  • all

  • app_data

  • asr

  • audio_duration

  • audio_properties

  • audiosecs

  • call_tag

  • caller

  • caller_v3

  • client

  • client_data

  • confidence

  • datetime

  • diarization_score

  • doc id

  • donedate

  • duration

  • ended

  • file

  • filenamelowercase

  • gender

  • jm_version

  • model

  • nchannels

  • nsubs

  • performance_stats

  • recvdate

  • recvtz

  • request id

  • requestid

  • sentiment

  • sentiment_scores

  • source

  • speakers

  • started

  • streamtags

  • tag

  • tid

  • transcript id

  • utterances

Although reserved field names may not be configured for folders, metadata values for those fields may be submitted in uploaded JSON as part of a reprocessing request. With the exception of the agentid, datetime, and duration fields, any submitted metadata values appear in the client_data section of the audio record's JSON output whether or not those metadata values were indexed.

Warning: Key values supplied for audio_properties, diarization_score, and jm_version are overwritten by the system. Any submitted values for these fields may be lost.

Using reserved fields

The key values for some reserved metadata fields may be client-supplied. For call center environments, values for agentid and datetime should be submitted as a best practice as they are very commonly used. Two additional fields, audio_duration and duration, may also be submitted, but should not be as a best practice. Overriding or failing to provide values for these fields as a part of processing flow may result in abnormal behavior as noted in the following list:

agentid

  • Variable length string limited to 100 characters.

  • The only searchable identifier for a single agent; required for applications to create and reference agent scorecards.

  • If a value is supplied for agent id, its value is interpreted in the same manner and stored in the agentid field.

  • If blank ("" or NULL), agentid's value displays as None.

datetime

  • Represents the audio's recording date and time.

  • If this value is not provided with audio data, the system ingestion time becomes the call's date of record.

  • String that may be expressed in any format compatible with the dateutil module for the standard Python module datetime.

  • In V‑Spark examples, expressed as YYYY-MM-DD HH:MM:SS.

  • Always assumed to be in the organization's time zone.

audio_duration and duration

  • Represents the audio recording's duration in seconds.

  • Users may override the system-generated value by providing any plain integer value for either the audio_duration or duration fields. The duration field takes precedence if both fields are provided.

  • Overriding this field is not recommended. Doing so is usually not necessary, and updating the field to the actual duration value requires reprocessing the audio.

  • To ignore client-supplied duration metadata values by default, enable the ignore_client_duration system configuration option.

Note: The agentid, audio_duration, datetime, and duration fields cannot be configured as custom metadata fields for a folder in any case because they are used by the system.