Metadata 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 fields.
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.
Important
Custom metadata field names should not begin with =
, +
, -
, or @
because these characters may cause unexpected system behavior.
Custom metadata field names beginning with +
or - are not included in search results. Field names beginning with any of the aforementioned characters are prefaced with an apostrophe '
in exported CSV reports to prevent spreadsheet applications from interpreting these labels as formulas.
Reserved Metadata Field Names
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.
Special Usage Considerations for Fields in the Reserved List
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.