Skip to main content

Uniphore Help Center Portal

Create Voice Conversation API

The Create Conversation API is used to upload and store audio files and auxiliary metadata for Conversation Insights Agent processing. You can upload one audio file at a time.

Currently, Conversation Insights Agent supports calls that have only these attributes—stereo, .wav, L16 PCM, 8k Hz.

Warning

Calls that do not have the above-mentioned attributes cannot be uploaded.

To initiate conversation processing, use the Process Batch Conversations API.

Endpoint

Method: POST

URL: https://<<Hostname>>/uzng-gateway/v1/conversation/voice

curl --location
'https://<Host name>/uzng-gateway/v1/conversation/voice'
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsIF0IjoxNzIxMjEyMDExLCJleHAiOjE3MjEyOTg0MTEsInNjb3BlIjoicmVhZDp0ZW5hbnRzIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwiYXpwIjoeyJhsDhg4ojQuQEZJOkkuYD1HMyFA'\
    --form 'audioFile=@"-Abu4Krji/591dd74f-0007-a283-3efb90d99955.wav"' \
    --form 'metaData=@"abCtg4CJe/metaData.json"'
Header Parameter
Authorization - Bearer <Token>

Note

To obtain an authorization token, click here.

Sample Request
{
    "metadata": {
        "sessionId": "8c382015-b64a-484a-baa9f391311c",
        "conversationRecordedDateTime ": 1719308465,
        "orgHierarchyId": "114",
        "direction": "Outbound",
        "isLeftChannelAgent": true,
        "isTestaaaaaaaaaaaaaaaaaaaaaaConversation": "False",
        "language": "en-us",
        "conversationType": "VOICE",
        "participants": [
            {
                "name": "Agent_01",
                "id": "42_D_U",
                "number": "12321",
                "role": "agent",
                "mailId": ngtest_sales_agent@uni.com },
            {
                "name": "Customer_01",
                "id": "93",
                "number": "275422",
                "role": "customer" }
        ],
        "auxiliaryMetaData": {
            "call_id": "b830ac47-c2e6-45fa-b063-0c51151ed952",
            "sale_or_no_sale": "Non Sale",
            "drm_or_do_id": "SEHYDO689151",
            "campaign_name": "Hyd_Digital_Mirror_Personal_Loan",
            "eval_local_datetime": "01-11-2023 09:34:31",
            "call_duration": "00:03:38",
            "language": "English",
            "location": "Hyderabad",
            "call_hold": "36000",
            "department": "Customer Service",
            "product_type": "Personal Loan",
            "reason_for_call": "Inquiry about loan terms",
            "call_resolution": "Provided information about loan repayment options",
            "customer_satisfaction": "Satisfied",
            "call_category": "Informational",
            "follow_up_required": "false",
            "call_priority": "Low",
            "call_source": "Website",
            "call_status": "Closed"         }
    }
}
Request Parameter

Parameter Name

Data Type

Description

Required/ Optional

audioFile

File

Recording of the conversation in .WAV format. Currently, only. WAV files are supported.

Required

metaData

Text

JSON request body including the conversation metadata as described below.

Note

The metadata parameters provided are samples and may vary for each customer.

Required

metadata: sessionId

String

Your unique ID of the conversation provided by the Organization / Customer.

Required

metadata: conversationRecordedDateTime

Date

The date and time of the recording in Epoch Timestamp format.

Required

metadata: orgHierarchyId

String

Node ID of the Organization Hierarchy. To obtain orgHierarchyId , refer Create Organization Hierarchy section.

Required

metadata: direction

Text

Direction of the call.

Example: Inbound, Outbound.

Required

metadata: isLeftChannelAgent

Boolean

If set to True, then the conversation from the Left Channel is Agent.

The first speaker in the transcript is the Agent.

Required

metadata: isTestConversation

Boolean

If set to True, the conversation will appear for validation in the Conversation Fact page.

Optional

metadata: language

String

Language of conversation.

Currently supports US English (en-us), Hindi, Arabic, and Spanish.

Required

metadata: conversationType

String

Channel of the conversation.

Currently supports Voice only.

Required

participants: name

String

Name of the participant involved in the conversation.

Required

participants: id

Number

ID of the participant.

Required

participants: number

Number

Participant’s contact number used in the conversation.

Optional

participants: role

String

Role of the participant.

Example: Agent, Customer

Required

participants: mailId

String

Email ID of the participant.

Required for participants with the Agent role.

Required

auxiliaryMetaData

String

Includes a list of specific information related to the call, such as call_id, product_type, reason_for_call, call_hold and more.

This data varies for each customer based on the nature of the call.

Note

call_hold value should be in milliseconds.

Required

Sample Response
{
  sessionId: "0243bffd-80aa-41f3-86ef-ddca85c9e0bb",
  message: null,
  requestAccepted: true
}
Response and Error Codes

Response Code

Condition

Message

Description

201

OK

Conversation created successfully.

This message appears when the audio file is successfully scheduled upload.

To check the upload status, refer to the Fetch Conversation Status API.

400

Bad Request

Invalid Request Body. Check the Request Body parameters.

Ensure the Request Body parameters are correct and in the right format.

401

UnAuthorized

Invalid token or invalid signature received for JSON Web Token validation.

Ensure the correct token is input.

429

Too Many Requests

The user has sent too many requests in a given amount of time (“rate limiting”).

Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

Retry after sometime.

500

Internal Server Error

Internal Server Error.

Retry after sometime.

In this section: