Skip to main content

Uniphore Help Center Portal

Create Chat Conversation API

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

Endpoint

Method: POST

URL: https://<<Hostname>>/batch-chat-connector/v1/messages

curl --location
'https://<Hostname>/batch-chat-connector/v1/messages'
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsIF0IjoxNzIxMjEyMDExLCJleHAiOjE3MjEyOTg0MTEsInNjb3QEZJOkkuYD1HMyFA'\
    --header 'Content-Type: application/json' \
    --data-raw '{
     "metadata": {
        "sessionId": "test-chat-12May-6",
        "conversationRecordedDateTime": 1746763214,
        "orgHierarchyId": "16991",
        "Environment": "prod",
        "direction": "Inbound",
        "language": "en-us",
        "participants": [
            {
                "name": "test agent19",
                "id": "2",
                "role": "agent",
                "mailId": "test_agent19@uni.com"
            },
            {
                "name": "Tom",
                "id": "1213",
                "role": "customer"
            }
        ],
        "isTestConversation": false
    },
    "auxiliaryMetadata": {
        "key1": "value1",
        "key2": "value2"
    },
   "messages": [
    {
        "participant.name": "Mark",
        "text": "hi i need to reset my password. can't log in",
        "timestamp": 1746075000
    },
    {
        "participant.name": "James Agent",
        "text": "Hi Mark! I'm sorry you're having trouble. Let's get that sorted. Can I have your email address associated with the account?",
        "timestamp": 1746075005
    },
    {
        "participant.name": "Mark",
        "text": "sure it's mark123@example.com",
        "timestamp": 1746075010
    },
    {
        "participant.name": "James Agent",
        "text": "Thanks! I've just sent a password reset link to your email. Please check your inbox or spam folder.",
        "timestamp": 1746075015
    },
    {
        "participant.name": "Mark",
        "text": "got it! reset the password and i'm back in. thanks a ton!",
        "timestamp": 1746075022
    },
    {
        "participant.name": "James Agent",
        "text": "Awesome! Glad to hear it's working now. Let me know if you need help with anything else",
        "timestamp": 1746075026
    },
    {
        "participant.name": "Mark",
        "text": "all good now. have a nice day!",
        "timestamp": 1746075030
    },
    {
        "participant.name": "James Agent",
        "text": "You too, Mark! Take care.",
        "timestamp": 1746075034
    }
]

}'
Header Parameter
Authorization - Bearer <Token>

Note

To obtain an authorization token, click here.

Sample Request Parameter
{
    "metadata": {
        "sessionId": "chat-30-Apr-1",
        "conversationRecordedDateTime": 1746002047,
        "orgHierarchyId": "253",

        "direction": "Inbound",
        "language": "en-us",
        "participants": [
          {
            "name": "James Agent",
            "id": "310",
            "role": "agent",
            "mailId": "jamesagent@uni.com"
          },
          {
            "name": "Tom",
            "id": "1213",
            "role": "customer"
          }
    
        ],
        "isTestConversation": false
    },

    "auxiliaryMetadata": {
        "key1" : "value1",
        "key2" : "value2"
    },
        "messages": [
    {
        "participant.name": "Mark",
        "text": "hi i need to reset my password. can't log in",
        "timestamp": 1746075000
    },
    {
        "participant.name": "James Agent",
        "text": "Hi Mark! I'm sorry you're having trouble. Let's get that sorted. Can I have your email address associated with the account?",
        "timestamp": 1746075005
    },
    {
        "participant.name": "Mark",
        "text": "sure it's mark123@example.com",
        "timestamp": 1746075010
    },
    {
        "participant.name": "James Agent",
        "text": "Thanks! I've just sent a password reset link to your email. Please check your inbox or spam folder.",
        "timestamp": 1746075015
    },
    {
        "participant.name": "Mark",
        "text": "got it! reset the password and i'm back in. thanks a ton!",
        "timestamp": 1746075022
    },
    {
        "participant.name": "James Agent",
        "text": "Awesome! Glad to hear it's working now. Let me know if you need help with anything else",
        "timestamp": 1746075026
    },
    {
        "participant.name": "Mark",
        "text": "all good now. have a nice day!",
        "timestamp": 1746075030
    },
    {
        "participant.name": "James Agent",
        "text": "You too, Mark! Take care.",
        "timestamp": 1746075034
    }
]

}
Request Parameter

Parameter Name

Data type

Description

Required/ Optional

sessionId

String

Unique ID of the conversation provided by the Organization / Customer.

Required

conversationRecordedDateTime

Date

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

Note

Ensure that the timeStamp contains values in seconds and does not include milliseconds.

Required

orgHierarchyId

String

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

Required

direction

Text

Direction of the call.

Example: Inbound, Outbound.

Required

language

String

Language of conversation.

Note

Reach out to the Uniphore Support team to learn about the languages supported currently.

Required

participants: name

String

Name of the participant involved in the conversation.

Required

participants: id

Number

ID of the participant.

Applicable for participants with the Agent role.

Required

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

isTestConversation

Boolean

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

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

auxiliaryMetadata

String

Includes a list of specific information related to the conversation, such as product_type, reason_for_conversation, and more.

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

Required

messages: participant.name

String

The name of the participant involved in the conversation turn.

Required

messages: text

String

The Chat conversation spoken by the participant in the turn.

Required

messages: timestamp

Date

The date and time of the conversation turn in Epoch Timestamp format.

Note

Ensure the first message's timestamp must be greater than or equal to the conversationRecordedDateTime.

Caution

Ensure that the timeStamp contains values in seconds and does not include milliseconds.

Required

Sample Response
{    "requestAccepted": true,    
     "sessionId": "test-chat-12May-6"
}
Response and Error Codes

Code

Condition

Message

Description

200

OK

sessionId: <<session id>>

Displays the session ID provided in the request.

400

Bad request

Field <<Parameter Name>> is empty or not provided.

This message is shown when the following fields are not provided in the request.

Parameter Name: OrghierarchyId, Direction, Language, Participant, Participant name, Timestamp.

Invalid <<Parameter Name>> passed.

This message is shown when an invalid parameter is passed in the request.

Timestamp of first message earlier than conversation recorded time

This message is shown when the timestamp of the first chat turn is greater than the actual conversation recorded time.

Ensure that the mandatory fields are provided in the request.

Ensure that no invalid parameter value is provided.

Ensure that no negative timestamp or invalid timestamp is provided.

500

Internal Server Error

Internal Server Error.

Retry after some time.

In this section: