# API access documentation

# Access preparation

# Get Accesskey

After the business cooperation is formed, our company will give the customer appId and appSecret. Please keep appSecret properly.

# Development and co-testing

The customer obtains the token through appId and appSecret, and puts the token in the header to request the corresponding interface.

# API docking method

# Public return parameters

After duix obtains the token and other request data sets, it will first conduct security verification and other verifications. After a series of verifications are passed, the data request sent this time will be processed. The parameter format returned by the platform is as follows:

field type Required remark
code String Y Response code
message String N Description information of success/error
data object N Specific content returned
success Boolean Y Success or not

Unless otherwise specified in the following text, the interpretation of return values refers to the internal structure of data.

# Common error

error code Description
0 normal
-1 fail
1005 token cannot be empty
1006 Token failure
1007 Script information does not exist
1009 Insufficient user availability
2002 Session information does not exist
40001 Invalid appid or appscrect
40002 internal error

# Get token

When docking with the duix-openapi-v2 platform, you need to generate your own token by referring to the following methods：

  1. Introducing Dependencies
<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>3.8.3</version>
</dependency>
  1. Java Example
import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;

import java.util.Calendar;
import java.util.Date;

/**
 * Create Signature
 *
 * @param appId  Issued to
 * @param secret secret
 * @param exp    Expiration time: in seconds
 * @return
 */
public static String createSig(String appId,String secret,int exp){
        Calendar nowTime=Calendar.getInstance();
        nowTime.add(Calendar.SECOND,exp);
        Date expiresDate=nowTime.getTime();

        return JWT.create()
        //Release time
        .withIssuedAt(new Date())
        //effective time
        .withExpiresAt(expiresDate)
        //load
        .withClaim("appId",appId)
        //encryption
        .sign(Algorithm.HMAC256(secret));
        }

# Verify signature

Interface address:

/duix-openapi-v2/sdk/checkSig

initiate API request: GET

Request data type: application/json

Response data type: application/json

# Interface description:

Verify the validity of the token and return the real-time interaction ws connection address of the digital person

# Request Parameter
name type Parameter transmission method Description
sig String Query token
# Response Parameter:
name type Description
appId String appId
wsService String Real time interactive ws address for digital humans

# management interface

Management HTTP requests have a common convention that requires passing tokens in the request header

# Obtain real-time concurrency of apps

# Interface address:

/duix-openapi-v2/v1/getconcurrentNumber

# initiate API request: GET

Interface description:

Query the concurrency of a certain APP

# Request Parameter
name type Parameter transmission method Description
appId String Query APPID

Response 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

# Interface address:

/duix-openapi-v2/v1/getconcurrentList

# initiate API request: GET
# Interface description:

Query the list of "in call" conversations on a certain app.

# Description
name type Parameter transmission method Description
appId String Query APPID

# Close all sessions of the app

# Interface address:

/duix-openapi-v2/v1/distroyCallSessionsByAppId

# initiate API request: GET
# Interface description:

Close all sessions under a certain app

# Description
name type Parameter transmission method Description
appId String Query APPID
# Response Example:
{
  "code": "",
  "data": "",
  "message": "",
  "success": true
}

# Close the specified session

# Interface address:

/duix-openapi-v2/v1/sessionStop

# initiate API request: GET
# Parameter
name type Parameter method Description
uuid String Query start-complete returned by the event sessionId

# Third-party prompt

# Other session integrations: Other platforms can be provided to digital human in the following ways. The DUIX platform can use your digital human to request a defined remote URL by using the POST method to obtain the answer to the question.
# Conversation platform integrations example: You can refer to this example. This open source application implements a conversation platform, and provides chat sessions.
# Request:The DUIX platform will send the question request to your remote URL through POST in the following format.
# Parameter
Field Type Description Required
sid String Your user ID, generated when you create a user. You can view it in the account information. Y
dh-code String The serial number is generated when each digital human is created and can be viewed in the overview. Y
dh-question String content questions Y
dh-conversation-id String Session id, a unique identifier Y
dh-context String Regarding the contextual information generated during this session, this information is stringified JSON format data. N
# response example:
{
  "sid": "100003",
  "dh-code": "187265485019156480",
  "dh-question": "who are you?",
  "dh-conversation-id": "0513e935-041f-48e0-9330-652ef4194511",
  "dh-context": "{}"
}