Skip to main content

Uniphore Help Center Portal

Ingest Conversation

Use the ingest conversation request to upload the .WAV audio file and associated metadata of a conversation previously captured outside of the platform.

Tested Configuration

A successful test of the ingest conversation API has been run. This test included single-threaded processing (one request at a time) of 90,000 mono-channel calls, each roughly 19MB in size, for a total ingest of roughly 1.62TB of audio data. To ensure that pod restarts do not risk the loss of ingested calls, graceful shutdowns have been implemented so that calls are fully processed before pods restart.

These calls were successfully tested against each Communication Recording Agent feature without issue. However, make note of the following:

  • Ingested calls are not processed by your Blocklist Policies, ensuring the calls you ingest are retained.

  • Ingested calls are not processed by your Lock Policies when they are ingested into the system.

  • Export Policies set with the Activate Instantly schedule do not process calls that have not yet been ingested. To ensure that Export Policies process your ingested calls, we recommend that your Export Policies use a repeating schedule.

Endpoint

Method: POST

URL: https://api.<region>.cloud.uniphore.com/media-preprocessor/v1/ingest-conversation

Content: multipart/form-data: metaData and audioFile

Request Parameters
metaData:

Parameter Name

Data Type

Description

Required/Optional

sessionID

Array

The unique external call ID. If a conversation is uploaded with an sessionID that already exists in the system, the new request is not processed, resulting in the newly attempted conversation not appearing in Communication Recording Agent - the response to this request would still return 202 accepted, this is due to the validation being processed later in the system.

Required

conversationRecordedDateTime

Number

The call start time, in the form of an epoch timestamp. The Recorded page in the Communication Recording Agent UI uses start time to filter conversations; that filter must be set to include the converted epoch timestamp for the ingested call to appear in the conversation list.

Required

direction

String

The direction of the call, either Inbound or Outbound.

Required

tenantId

String

The ID of the tenant ingesting the conversation data. The bearer token provided with the request must have access to the tenant specified using tenantId.

Required

participants

Array

A list of the participants on the call, each with the following optional sub-parameters:

  • name - The name of the agent or customer.

  • id - the ID of the agent or customer.

  • role - the role of the participant.

  • mailId - the Email ID of the agent if the agent is provisioned. Conversations are mapped to tenant agents based on this parameter if provided.

  • number - the agent or customer's number.

Optional

AuxiliaryMetaData

Array

An array of additional metadata associated with the conversation. Any sub-parameters are optional, and there is no restriction on the metadata fields to include here.

Metadata listed here can be paired with Communication Recording Agent metadata fields using the metadata mapping API.

Any unmapped metadata provided in ingest requests appears in the conversation's Other Properties in the Communication Recording Agent UI.

Note

The metadata mapping API can split the metadata values listed in AuxiliaryMetaData to pair parts of the metadata to different Communication Recording Agent metadata fields.

Important

If the sub-parameter wavfile is included, the value must match the name of the file uploaded in the audioFile part of the request form. For example, 7543937365.wav.

Required

For an example request, see Sample Request.

audioFile

Upload the .WAV audio file for the conversation.

Response and Error Code

Response Code

Condition

202

Conversation ingestion request accepted.

400

Invalid request or validation failure.

401

Unauthorized - invalid or missing token/ not enough permission to use API.

500

Internal Server Error.

Sample Request
{
    "sessionId": "000-external-call-id-8755478",
    "conversationRecordedDateTime": "1765975842",
    "direction": "Inbound",
    "tenantId": "67hg8362-g3d2-7g92-9273-d9h02kr83736",
    "participants": [
        {
            "name": "John Smith",
            "id": "87548",
            "role": "agent",
            "mailId": "JohnSmith@example.com",
            "number": "201 111 1111"
        },
        {
            "name": "Jane Doe",
            "id": "1090948",
            "role": "customer",
        }
    ],
    "auxiliaryMetaData": {
        "Extension": "john@334"
    }
}
In this section: