# OpenAPI Integration

# Prerequisites

# Generate Signature to Get Token

When integrating with the duix-openapi-v2 platform, you need to integrate token generation code in your platform. You can refer to the following code for generating tokens:

How to Get Token (opens new window)

# Verify Token

API Endpoint:

/duix-openapi-v2/sdk/checkSig

Request Method: GET

Request Data Type: application/json

Response Data Type: application/json

# Description:

Verify token validity and return the WebSocket connection address for real-time digital human interaction

# Parameters
Parameter Name Type Pass Method Description
sig String Query Same as token
# Response Parameters:
Parameter Name Type Description
appId String appId
wsService String WebSocket address for digital human interaction

# Management Interfaces

Management HTTP requests have a common requirement: the token must be passed in the request header

# Interaction Flow

image.png

# Get APP Real-time Concurrency

# API Endpoint:

/duix-openapi-v2/v1/getconcurrentNumber

# Request Method: GET

Description:

Query the number of concurrent connections under an APP

# Parameters
Parameter Name Type Pass Method Description
appId String Query APPID created from platform

Response Parameters:

Parameter Name Type
code String
data ConcurrentStatus
cropId String
totalConcurrentNumber integer(int32)
userConcurrentNumber integer(int32)
message String
success boolean

Response Example:

{
  "code": "",
  "data": {
    "cropId": "",
    "totalConcurrentNumber": 0,
    "userConcurrentNumber": 0
  },
  "message": "",
  "success": true
}

# Get APP Real-time Sessions

# API Endpoint:

/duix-openapi-v2/v1/getconcurrentList

# Request Method: GET
# Description:

Query the list of "in-call" sessions under an APP.

# Parameters
Parameter Name Type Pass Method Description
appId String Query APPID created from platform

# Close All APP Sessions

# API Endpoint:

/duix-openapi-v2/v1/distroyCallSessionsByAppId

# Request Method: GET
# Description:

Close all sessions under an APP

# Parameters
Parameter Name Type Pass Method Description
appId String Query APPID created from platform
# Response Example:
{
  "code": "",
  "data": "",
  "message": "",
  "success": true
}

# Close Specific Session

# API Endpoint:

/duix-openapi-v2/v1/sessionStop

# Request Method: GET
# Parameters
Parameter Name Type Pass Method Description
uuid String Query sessionId field returned by the start-complete event

# Third-party Dialogue Integration (Non-streaming)

# Other Session Integration: Other session platforms can provide their services to digital humans through the following method. The DUIX platform can get answers to questions through your digital human by making POST requests to a remote URL you define.
image.png
# Session Platform Integration Example: You can refer to this session platform integration example. This open-source application implements a dialogue platform integration that provides casual conversation functionality.
# Request Specification: The DUIX platform sends question requests (questions asked by customers to your digital human) in the following format via POST to your remote URL.
# Parameters
Field Type Description Required
sid String Your user ID, generated when creating a user. Can be viewed in account information. Y
dh-code String Digital human code, generated when creating each digital human, can be viewed in digital human overview. Y
dh-question String The question content you want to ask the digital human Y
dh-conversation-id String Session ID, unique identifier for the session Y
dh-context JSON Context information generated during the session, in JSON array format. N
dh-context.q JSON User's speech content N
dh-context.a JSON Digital human's speech content N
# Request Example:
{
  "sid": "100003",
  "dh-code": "187265485019156480",
  "dh-question": "who are you?",
  "dh-conversation-id": "0513e935-041f-48e0-9330-652ef4194511",
  "dh-context": [
        {
            "q": {
                "context": "."
            },
            "a": {
                "context": "Hello, how can I help you?"
            }
        },
        {
            "q": {
                "context": "What are you good at?"
            },
            "a": {
                "context": "As an AI assistant, I'm good at handling various tasks"
            }
        }
    ]
}

Response Specification: When you receive a question request, you need to respond in the following format.

Field Type Required Description
code String Y Response status code
msg String N Success/error description
data object N Specific response content
success Boolean Y Whether successful

Valid Response Types:

Code Status Response
200 OK Response body following specification below
400 Bad Request Request body/headers are invalid
401 Unauthorized Authentication information invalid
403 Forbidden Authentication failed
500 Server Error Service exception

Response Body Specification:

Field Type Description Required
conversationId String Session ID, unique identifier for the session, same as dh-conversation-id in request parameters. Y
question String Question asked by the user. N
answer String Answer to the user's question to the digital human, this is a stringified JSON object. Y
intent String Intent matched on the platform N
errorMsg String Description of exception or error N
extra String Additional information, JSON string N
{
  "code": "200",
  "msg": "Processing successful",
  "success": true,
  "data": {
    "conversationId": "0513e935-041f-48e0-9330-652ef4194511",
    "question": "who are you?",
    "answer": {
      "answer": "Welcome to UneeQ, how can I help?",
      "operations": {
        "tipPhrases": {
          "phrases": ["yes", "no"]
        },
        "canShowText": 1
      }
    },
    "intent": "introduce"
  }
}

# Third-party Dialogue Integration (streaming)

# Other Session Integration: Other session platforms can provide their services to digital humans through the following method. The DUIX platform can get answers to questions through your digital human by making POST requests to a remote URL you define.
image.png
# Session Platform Integration Example: You can refer to this session platform integration example. This open-source application implements a dialogue platform integration that provides casual conversation functionality.
# Request Specification: The DUIX platform sends question requests (questions asked by customers to your digital human) in the following format via POST to your remote URL.
# Parameters
Field Type Description Required
sid String Your user ID, generated when creating a user. Can be viewed in account information. Y
dh-code String Digital human code, generated when creating each digital human, can be viewed in digital human overview. Y
dh-question String The question content you want to ask the digital human Y
dh-conversation-id String Session ID, unique identifier for the session Y
dh-context JSON Context information generated during the session, in JSON array format. N
dh-context.q JSON User's speech content N
dh-context.a JSON Digital human's speech content N
# Request Example:
{
  "sid": "100003",
  "dh-code": "187265485019156480",
  "dh-question": "who are you?",
  "dh-conversation-id": "0513e935-041f-48e0-9330-652ef4194511",
  "dh-context": [
        {
            "q": {
                "context": "."
            },
            "a": {
                "context": "Hello, how can I help you?"
            }
        },
        {
            "q": {
                "context": "What are you good at?"
            },
            "a": {
                "context": "As an AI assistant, I'm good at handling various tasks"
            }
        }
    ]
}

Response Specification: When you receive a question request, you need to respond in the following format.

Field Type Required Description
code String Y Response status code
msg String N Success/error description
data object N Specific response content
success Boolean Y Whether successful

Valid Response Types:

Code Status Response
200 OK Response body following specification below
400 Bad Request Request body/headers are invalid
401 Unauthorized Authentication information invalid
403 Forbidden Authentication failed
500 Server Error Service exception

返回体规范:

Field Type Description Required
answer String Returned answer Y
isEnd boolean End marker Y
{
    "answer": "I'm good at handling various tasks",
    "isEnd": false
}

Example of Spring Boot streaming

@RestController
@RequestMapping("test")
public class TestApi {
    @PostMapping(value = "/thirdStreamExample", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<Map> thirdStreamExample(@RequestBody JSONObject message) {

        Map end = new HashMap<>();
        end.put("isEnd", true);

        return Flux.interval(Duration.ofSeconds(1)).map(t -> {
            Map answerResp = new HashMap();
            answerResp.put("answer",  t + ". I'm good at handling various tasks");
            answerResp.put("isEnd", false);
            return answerResp;
        }).take(5).concatWithValues(end);
    }
}