General information
The following sections provide general information about base paths, API content and codec formats, the metadata format, and use of internal Verint identifiers:
Base Path - Multimedia Ingestion API
Verint APIs adhere to the URI conventions defined in the Verint API Guidelines. Because the base path varies by environment, all endpoints in this guide must be appended to the correct base path for your deployment type (Cloud or on‑prem), regional gateway, and API version.
|
Environment |
Base path |
Placeholders |
|---|---|---|
|
Cloud |
https://<regional-api-gateway>/edm/ingestion/<version> |
|
|
On-prem |
https://<hostname>/api/recording/ingestion/<version> |
|
URI Structure (Verint API Guidelines)
Supported content and codec formats
|
Content type |
MIME type |
Description |
|---|---|---|
|
Audio |
audio/vnd.verint.wav |
Audio must be uploaded in Verint supported formats in a wav container file. Audio files can be mono (1 channel) or stereo (2 channel) and include all the following in 8 kHz sampling rate unless otherwise noted:
Formats other than the ones listed can be supported. Contact Verint Product Management for information about custom services or off-the-shelf services that are available. |
|
Screen |
screen/vnd.verint.capb |
Screen files only support original files created by Verint screen |
|
Video |
video/vnd.verint.mp4 |
Video files must be in Advanced Video Coding (AVC) format, also referred to as H.264 or MPEG-4 (MP4). For proper replay, use the fast-start option. |
|
Screen Share |
share/vnd.verint.mp4 |
Represents a screen share media in a collaboration or conference. Video files must be in Advanced Video Coding (AVC) format, also referred to as H.264 or MPEG-4 (MP4). For proper replay, use the fast-start option. |
Metadata document format
The metadata must be uploaded in a json document with a specific format. Typically this metadata is for a single contact and content for an audio interaction with 1 audio wav file.
|
JSON Schema Element |
Type |
Required |
Description |
|---|---|---|---|
|
api |
Object |
Optional |
Only supported in v3. Controls the behavior of the API, including the handling of agent resolution. See API object in Metadata (v3) for details. |
|
contents[] |
Array of objects |
Required |
List of contents to associate to this Session. Each content item needs to map to an existing inum in the system or an uploaded content file as part of this interaction. |
|
contents[].index |
Integer |
Optional |
Index of the content for future upload. Not required if the content references an existing INUM. |
|
contents[].content_type |
String |
Required |
Type of content referenced. Playable media must use the following formats:
|
|
contents[].start_time |
Date Time |
Required |
Start time of the content. This value is compared to the interaction (session) start time for rendering. |
|
contents[].end_time |
Date Time |
Optional |
Ending time of the content. |
|
contents[].swap_audio_channels |
Boolean |
False |
A value of a true swaps the left and right audio channel at the time of ingestion. The default value is false. |
|
contents[].channel |
String |
False |
An indicator identifies whether the content is from an agent and ensures it is assigned to the left channel when merging two mono WAV files into a stereo format one channel capturing the agent’s voice and the other capturing the customer or a second agent. This configuration preserves speaker separation for enhanced clarity in analysis, playback, and processing. |
|
contents[].original_filename |
String |
False |
The name of the original file. |
|
contacts[] |
Array of objects |
Optional |
List of contacts being uploaded. Typical lists only have one item in the array. |
|
contacts[].start_time |
Date Time |
Required |
Start time of the contact being uploaded. |
|
contacts[].end_time |
Date Time |
Required |
End time of the contact being uploaded. |
|
contacts[].ani |
String |
Optional |
The ANI or From party for the overall contact. Typically this value is the customer on an inbound contact. |
|
contacts[].dnis |
String |
Optional |
The DNIS or To party. Typically this value is the first agent extension on an inbound contact. It can also be DID or 800 inbound phone number or a queue. |
|
contacts[].direction |
String |
Optional |
Indicates the overall direction of the contact. Can be one of the following:
|
|
contacts[].number_of_conferences |
Integer |
Optional |
The number of conferences that occurred during this contact. |
|
contacts[].number_of_holds |
Integer |
Optional |
The number of holds that occurred during this contact. |
|
contacts[].number_of_transfers |
Integer |
Optional |
The number of transfers that occurred during this contact. |
|
contacts[].total_hold_time |
Integer |
Optional |
The total time (in seconds) that the contact was on hold. |
|
contacts[].sessions[] |
Array of objects |
Optional |
List of sessions being uploaded. Typically this value is one item, but in a multi-interaction (session) contact, it can be multiple items. |
|
contacts[].sessions[].wrapup_time |
Integer |
Optional |
The number of seconds to record agent screen activity after the customer leaves the call. |
|
…sessions[].start_time |
Date Time |
Required |
Start time of the session. (Length should not be more than 24-hours). |
|
…sessions[].end_time |
Date Time |
Required |
End time of the session. (Length should not be more than 24-hours). |
|
…sessions[].interaction_type |
String |
Optional |
Type of interaction being uploaded. It can be one of the following:
|
|
…sessions[].direction |
String |
Optional |
Indicates the direction of the interaction. Can be one of the following:
|
|
…sessions[].ani |
String |
Optional |
The Automatic Number Identification (ANI) is usually the telephone number of the person who made the call. It identifies who the call is from. |
|
…sessions[].dnis |
String |
Optional |
The Dialed Number Identification Service (DNIS) is the originally dialed telephone number. It identifies who the call is to. |
|
…sessions[].extension |
String |
Optional |
The extension or device to which the interaction is associated. |
|
…sessions[].pbx_login_id |
String |
Optional |
The login of the user. This value is typically a telephony login id or an NT Login id for the workstation. |
|
…sessions[].agent_id |
Integer |
Optional |
The internal Verint identifier of the employee. If configured on a data source, the pbx_login_id can be used to look up the user. |
|
…sessions[].switch_id |
Integer |
Optional |
The internal Verint identifier of the data source the interaction is associated to. |
|
…sessions[].switch_call_id |
String |
Optional |
Located in the session.switch_call_id field of the system. This element can be used to reference an external system id for the interaction. |
|
…sessions[].is_mute |
Boolean |
Optional |
Indicates if muting or pausing happened during this interaction |
|
…sessions[].number_of_holds |
Integer |
Optional |
Count of the number of holds that happened during this interaction. |
|
…sessions[].time_offset |
Integer |
Optional |
Indicates the offset of this call from UTC timezone. In the format of positive or negative minutes from UTC. Example: '-300' |
|
…sessions[].total_hold_time |
Integer |
Optional |
The total time (in seconds) that the interaction was on hold. |
|
…sessions[].tags[] |
Array of objects |
Optional |
Array of events included in the UI display for the interaction. |
|
…tags[].event_type |
String |
Required |
Type of event for this tag. It can be one of the following:
|
|
…tags[].event_time |
Date Time |
Required |
Time that the event happened. This value is an absolute time and the UI displays it in relation to the session[].start_time. |
|
…tags[].tagged_by_component |
String |
Optional |
User indication of what created the tag. |
|
…tags[].attributes[] |
Object |
Optional |
Array of Key values pairs that occurred on this tag. Example: { "ANI": "7703492341", "DNIS": "8003391023", "Skill": "Sales" } |
API object in Metadata (v3)
In Multimedia Ingestion v2, the following api_object tags change how interactions are processed. Use these tags to capture interactions from unknown agents, and to redact and morph call audio.
An interaction is assigned to a specific agent using the session agent id or the pbx_login_id. However, if both those fields fail to resolve, it is still possible to capture interactions from an unknown agent by setting allow_missing_agent to true and including the default_agent_id, which contains the ID of the default agent assigned to your data source.
An interaction is rejected and the API returns an error message when:
-
allow_missing_agent is set to false
-
pbx_login_id does not match any of the Employee IDs assigned to your data source
-
sessions[].agent_id is missing or does not match a valid qm_analytics_employee_id in the system.
-
default_agent_id is missing or does not match a valid qm_analytics_employee_id in the system
|
API object element |
Type |
Required |
Description |
|---|---|---|---|
|
api.allow_missing_agent |
Boolean |
Optional |
When allow_missing_agent is set to false, and the agent can’t be resolved because the pbx_login_id does not match any of the Employee IDs assigned to your data source, then a 4xx error is returned. The error provides specific details about the problem. When allow_missing_agent is set to true, the API can accept the POST without an agent_id present. This behavior is similar to how the v2 api worked. |
|
api.default_agent_id |
Integer |
Optional |
Specifies the ID number of the default employee account assigned to the data source. If the …sessions[].agent_id is missing, then this default value is used to tag the interaction. |
|
api.requires_redaction |
Boolean |
Optional |
When "requires_redaction" is marked as true in an interaction. Only users with the required privileges can choose to listen to the redacted portions of call audio when they replay or export the call. This allows agents to protect a customer's sensitive data, such as their credit card information. |
|
api.requires_morphing |
String |
Optional |
To protect a person's identity, apply morphing to the agent channel or to both the agent and customer channels so that the person speaking cannot be identified by their voice. Only users with the required privileges can replay or export a call without the morphing. Accepted values: "Agent" or "Both". Leaving the value blank will mark the interaction as no morphing. |
Ingestion v3 Examples
|
Request |
Response |
Comment |
|---|---|---|
|
api.allow_missing_agent : no effect api.default_agent_id: 123 * contacts[].sessions[].agent_id: blank or not provided contacts[].sessions[].pbx_login_id: not provided or provided but no employee found * agent_id 123 is valid in the system. |
201 Created |
The result is a session marked and associated to the employee with agent_id 123. |
|
api.allow_missing_agent: false or not provided api.default_agent_id: blank or not provided contacts[].sessions[].agent_id: blank or not provided - contacts[].sessions[].pbx_login_id : not provided |
400 Bad Request |
The result is a 400 Bad Request, which indicates that none of the required details are provided in the request. |
|
api.allow_missing_agent: false or not provided api.default_agent_id: 123* contacts[].sessions[].agent_id: blank or not provided contacts[].sessions[].pbx_login_id: provided but no employee found * agent_id 123 is NOT valid in the system. |
409 Conflict |
The result is a 409 Conflict to indicate that no employee exists with id 123 (default_agent_id). |
|
api.allow_missing_agent : true api.default_agent_id : 123* contacts[].sessions[].agent_id : blank or not provided contacts[].sessions[].pbx_login_id : not provided or provided but no employee found * agent_id 123 is NOT valid in the system. |
201 Created |
Because a missing agent is explicitly allowed, the request is accepted. However, the invalid agent_ID 123, specified as the default, is not used. |
Verint internal identifiers in the JSON metadata document
Three fields in the JSON metadata document are internal Verint identifiers:
- agent_id: The unique identifier for the employee.
- organization_id: The ID of the organization that the interaction is associated to.
- switch_id: The ID of the data source switch that the interaction is associated to.
The client can explicitly set these three fields, or the ingestion service can locate them using the pbx_login_id associated to the employee.
If the pbx_login_id is set, the system attempts to find a user with that specific identifier assigned as an employee Id on a specific data source.
If more than one employee is found with the specified id, the system does not perform any processing. If one employee is returned, then the agent_id, organization_id and datasource_id are updated for that employee.
If the agent cannot be resolved, a 409 Conflict is returned unless api.allow_missing_agent is true. If v2 API is being used, the session is ingested but missing_agent_association field is returned in the result with a value of true.