Callback Interface Description

The connection callback URL of agent bidirectional calls can be configured only on the GUI. A tenant administrator can choose Configuration Center > Expansion Management > Bidirectional Call to set Connection Callback URL.
The release callback URL for agent bidirectional calls can be configured using either of the following methods:
1. Configuration on the GUI: A tenant administrator chooses Configuration Center > Expansion Management > Bidirectional Call to set Hang-up Callback URL.
1. Configuration using the call creation interface (V1.0.0): The request parameter callBackUrl can be transferred when the call creation interface (V1.0.0) is invoked.
- For configuration of the release callback URL on the GUI, no URL authentication is performed. No authentication may cause security risks. Exercise caution when using this mode.
- If the release callback URL is configured using both methods, the value of callBackUrl transferred using the call creation interface (V1.0.0) is used.

Description of the Agent Bidirectional Call Callback Interface Signature Algorithm

Signature algorithm (authentication) prerequisites
The release callback URL has been transferred using the call creation interface (V1.0.0), and Callback URL Authentication Mode has been set to Shared Key on the callback URL configuration page.

Authentication procedure
1. When the system calls back the release callback URL, if the signing conditions are met, the following parameters are added to the input parameters of the interface:
  timestamp: current timestamp
  
  nonce: random string
  
  signature: authentication signature
2. After the customer receives the callback request, an authentication signature is generated based on the signature algorithm and will be verified based on the input parameter signature. The verification passes upon consistency.

Signature string generation method
1. Sort all request parameters (except timestamp, nonce, and signature) in alphabetical order based on the parameter name and combine them into a string using commas (,). For example, the parameters in {"b":"2", "a":1, "d":"null", "c":""} are sorted and combined into the string "a=1,b=2,c=,d=null".
2. Generate the values of timestamp (timestamp) and nonce (random string) and combine them with the value of appSecret (shared key configured on the GUI) and the string generated in 1 using underscores (_). The format is {Value of appSecret}_{Value of timestamp}_{Value of nonce}_{String generated in 1}.
3. Encrypt the value into a byte array using the SHA256 algorithm and encode the array using Base64.

Reference code

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

private String generateSinature(TreeMap<String, Object> callbackParametters, String nonce, long timestamp, String appSecret) {
    // {Value of appSecret}_{Value of timestamp}_{Value of nonce}_Parameters
    // Sort the parameters in {"b":"2", "a":1, "d":"null", "c":""} and combine them into the string "a=1,b=2,c=,d=null".
    String paramStr = callbackParametters.toString().replace(" ", "");
    String toSignString = appSecret + "_" + timestamp + "_" + nonce + "_" + 
           paramStr.substring(1, paramStr.length() - 1);
    return Base64.encodeBase64String(tokenByHmacSha256(toSignString.getBytes(StandardCharsets.UTF_8), appSecret));
}

public static byte[] tokenByHmacSha256(byte[] dataBytes, String appSecret) {
    try {
        Mac mac = Mac.getInstance("HmacSHA256");
        byte[] key = appSecret.getBytes(StandardCharsets.UTF_8);
        SecretKeySpec secretKey = new SecretKeySpec(key, "HmacSHA256");
        mac.init(secretKey);return mac.doFinal(dataBytes);
    } catch (Exception e) {
        LOGGER.error("tokenByHmacSha256 failed: ", e);throw new RuntimeException("HmacSha256 run failed.");
    }
}