UploadAudioData

Process description

Call the API to upload audio quality inspection => Convert the recording file to text => Separate roles in the text based on the specified channel splitting method (distinguish between agent and customer) => Analyze using quality inspection rules => Quality inspection complete.

Task execution efficiency

The speed of task execution depends on the speed of converting the recording file to text. Ideally, a 5-minute recording file can be transcribed within 2 minutes. However, when the transcription service has many queued tasks, there will be a queuing wait time. Generally, transcription completes within 6 hours, except for bulk uploads of large-scale data (more than 500 hours of recordings uploaded within 30 minutes). After transcription is complete, quality inspection analysis takes only milliseconds.

Recording file URL requirements

• Supports single-channel/dual-channel WAV and MP3 format recording files. The file size must be less than 512 MB.

• The URL must be an HTTP-accessible URL address. Local file submission is not supported. The recording file access permissions must be set to public.

• The URL can only use domain names, not IP addresses. The URL cannot contain spaces. Avoid using Chinese characters.

• After converting the recording to text, the system deletes the downloaded recording file and does not retain a copy.

• If your recording URL has an access expiration period (for example, the recording is stored in Alibaba Cloud OSS and you specified an expiration period when generating the recording URL through OSS), set the expiration period to at least 12 hours, or 24 hours if possible. This is because file transcription takes time and occasional queuing may occur. If the queuing time is long, the recording is downloaded only when transcription begins. This prevents the recording URL from expiring before the download.

• After quality inspection analysis is complete, the recording is still played using the URL you provided when reviewing files in the console. Ensure that the URL remains active long-term. Otherwise, the recording cannot be played.

Role separation description

After the recording is converted to text, the system automatically separates the text into two conversation roles. However, the system cannot determine which role is the agent and which is the customer. You need to perform role separation based on certain rules. The accuracy of role separation is critical because the rules used for quality inspection analysis often have role detection restrictions (a rule only checks the agent or the customer). If role separation is incorrect, the accuracy of quality inspection results is significantly affected.

Recording files are typically divided into two types: single-channel (mono) and dual-channel (stereo):

• Single-channel recording: The voices of both the agent and customer are stored on one channel. After the recording file is converted to text, the system uses a built-in algorithm to distinguish between two roles. By setting a list of keywords that the agent is likely to say, the system analyzes the transcribed text sentence by sentence from top to bottom. When a sentence matches a keyword, the role of that sentence is determined to be the agent, and the other role is the customer. For details, see recognizeRoleDataSetId and serviceChannelKeywords in the request parameters. Due to the unpredictability of conversation content (for example, cross-talk between two roles or both people speaking simultaneously), role separation for single-channel recordings cannot be guaranteed to be 100% accurate. Save recording files as dual-channel recordings whenever possible.

• Dual-channel recording: The voices of the agent and customer are stored on two separate channels. Even if the conversation overlaps, the recording-to-text conversion can accurately distinguish between the two. Specify the agent and customer by using the serviceChannel and clientChannel request parameters.

Retrieve quality inspection analysis results

Because recording file recognition is not real-time, you need to asynchronously retrieve quality inspection analysis results. The following three methods are available:

• Message notification: For details, see MSMQ. After receiving a message, invoke the GetResult operation to retrieve detailed results. (Recommended)

• Callback: Specify a callbackUrl in the request parameters. The system initiates a callback after the task is complete. After receiving the callback, invoke the GetResult operation to retrieve detailed results.

• Polling: The operation returns a task ID (taskId). Use the taskId to poll the getResult operation to asynchronously retrieve results. Check whether the status in the response parameters indicates completion. Do not set the polling interval too short. Analysis normally completes within a few minutes. Set the polling interval to 30 seconds or more. (Not recommended)

Request parameters and JSON string information

Property	Type	Required	Description
callList	List	Yes	The collection of voice files. You can upload multiple recording files at a time. For details, see jsonStr.callList property description below.
autoSplit	Integer	No	Applicable to single-channel recordings in most cases. Valid values: 0, 1. Specifies whether to automatically split channels. 1 indicates automatic channel splitting, and 0 indicates no splitting. Default value: 1. If set to 1, the uploaded audio is single-channel. Automatic channel splitting requires additional processing time. If the recording is dual-channel, this parameter must be set to 0.
enableAutoSplitByLLM	Boolean	No	Specifies whether to use LLM-based automatic role separation parameter settings for this recording file. If set to true, the LLM intelligent role separation feature is used. Default value: false.
recognizeRoleDataSetId	Long	No	The dataset ID. Uses an existing dataset because the dataset has role separation rules configured at creation (see Speaker Role Settings in the Create Dataset feature). Specifying a dataset ID here applies the role separation rules of that dataset to the uploaded file. Applicable to single-channel recordings.
serviceChannelKeywords	List	No	Applicable to single-channel recordings in most cases. Sets a list of keywords that the agent is likely to say (ensure the keywords are highly distinctive). The system analyzes the transcribed text sentence by sentence from top to bottom. When a sentence hits a keyword, the role of that sentence is determined to be the agent, and the other role is the customer. When both recognizeRoleDataSetId and serviceChannelKeywords are specified, recognizeRoleDataSetId takes higher priority. If neither is set, the system uses built-in channel splitting rules as a fallback.
serviceChannel	Integer	No	Applicable to dual-channel recordings. Specifies the channel number of the agent role. Valid values: 0, 1. Default value: 0, meaning channel 0 is the agent. Channels are typically numbered starting from 0, so two channels are 0 and 1. Determine whether channel 0 is the agent or customer on your own. If you use this parameter, you must also pass the autoSplit parameter with a value of 0. Ignore this parameter for single-channel files.
clientChannel	Integer	No	Applicable to dual-channel recordings. Specifies the channel number of the customer role. Valid values: 0, 1. Default value: 1, meaning channel 1 is the customer. Channels are typically numbered starting from 0, so two channels are 0 and 1. Determine whether channel 0 is the agent or customer on your own. If you use this parameter, you must also pass the autoSplit parameter with a value of 0. Ignore this parameter for single-channel files.
sampleRate	Integer	No	The sample rate of the recording file. Valid values: 8 (8000 Hz), 16 (16000 Hz). Default value: 8. Specify the correct sample rate for the recording file. An incorrect sample rate causes incorrect transcription results. Recordings generated by call centers typically have a sample rate of 8000 Hz.
callbackUrl	String	No	The callback URL. If not specified, no callback is initiated. Ensure the callback URL is publicly accessible over the Internet. IP addresses are not supported. A callback is initiated after recording analysis is complete. For details, see Callback parameter description below.

jsonStr.callList property description

Property	Type	Required	Description
voiceFileUrl	String	Yes	The recording file URL. For specific requirements, see Recording file URL requirements in the API description.
fileName	String	No	The audio file name, such as audio.wav. Although not required, provide this parameter for statistical purposes. If not provided, the name is extracted from voiceFileUrl. For example, for http://www.aliyun.com/audio.wav, the file name is parsed as audio.wav.
autoSplit	Integer	No	See the parent object metric description. If empty, the value from the parent object is used.
recognizeRoleDataSetId	Long	No	See the parent object metric description. If empty, the value from the parent object is used.
serviceChannel	Integer	No	See the parent object metric description. If empty, the value from the parent object is used.
clientChannel	Integer	Yes	See the parent object metric description. If empty, the value from the parent object is used.
sampleRate	Integer	No	See the parent object metric description. If empty, the value from the parent object is used.
callStartTime	Long	No	The time when the recording occurred, in milliseconds since January 1, 1970, 00:00:00 GMT (millisecond timestamp, for example: 1584535485856). If not specified, the current time is used.
customerServiceId	Long	No	The agent ID. Obtain this from the console under Basic Settings > Personnel Management. When the correct agent ID is provided, the agent can view associated recording files when logging in to the control tower.
customerServiceName	String	No	The agent name.
skillGroupId	String	No	The skill group ID.
skillGroupName	String	No	The skill group name.
callType	Integer	No	The call type. Valid values: 1: outbound. 3: inbound.
callee	String	No	The callee number. For outbound calls, this is the customer number. For inbound calls, this is the agent number.
caller	String	No	The caller number. For outbound calls, this is the agent number. For inbound calls, this is the customer number.
callId	String	No	The call ID. This can be the call ID from the call center system or any other ID that identifies the call.
business	String	No	The business line name. This is custom data used for classification and statistics.
callUuid	String	No	The globally unique identifier used for idempotency (deduplication). If this field is provided, the system checks whether the same callUuid exists in data uploaded within the last two hours. If it exists, the current upload request is rejected.
sessionGroupId	String	No	The session group ID. Typically, sessions between the same agent and the same customer are called a session group. After providing a session group ID, you can view quality inspection results at the session group level on the session group results page. (Applicable to the new version of Intelligent Speech Analytics only)
customerId	String	No	The customer ID. (Applicable to the new version of Intelligent Speech Analytics only)
customerName	String	No	The customer name. (Applicable to the new version of Intelligent Speech Analytics only)
schemeTaskConfigId	String	No	The manually specified quality inspection task ID. When manually specified, the specified quality inspection task is used for inspection. (Applicable to the new version of Intelligent Speech Analytics only)
remark1	String	No	Custom data 1. Stores custom fields related to your business. Maximum length: 64 characters.
remark2	String	No	Custom data 2. Stores custom fields related to your business. Maximum length: 64 characters.
remark3	String	No	Custom data 3. Stores custom fields related to your business. Maximum length: 64 characters.
remark4	String	No	Custom data 4. Stores custom fields related to your business. Maximum length: 64 characters.
remark5	Long	No	Custom data 5. Stores custom fields related to your business. Format: signed long.
remark6	String	No	Custom data 6. Stores custom fields related to your business. Maximum length: 1024 characters.
remark7	String	No	Custom data 7. Stores custom fields related to your business. Maximum length: 64 characters.
remark8	String	No	Custom data 8. Stores custom fields related to your business. Maximum length: 64 characters.
remark9	String	No	Custom data 9. Stores custom fields related to your business. Maximum length: 64 characters.
remark10	String	No	Custom data 10. Stores custom fields related to your business. Maximum length: 64 characters.
remark11	String	No	Custom data 11. Stores custom fields related to your business. Maximum length: 64 characters.
remark12	String	No	Custom data 12. Stores custom fields related to your business. Maximum length: 64 characters.
remark13	String	No	Custom data 13. Stores custom fields related to your business. Maximum length: 64 characters.
remark14	Long	No	Custom data 14. Stores custom fields related to your business. Format: signed long.
remark15	Long	No	Custom data 15. Stores custom fields related to your business. Format: signed long.
remark16	String	No	Custom data 16. Stores custom fields related to your business. Maximum length: 64 characters.
remark17	String	No	Custom data 17. Stores custom fields related to your business. Maximum length: 64 characters.
remark18	String	No	Custom data 18. Stores custom fields related to your business. Maximum length: 64 characters.
remark19	String	No	Custom data 19. Stores custom fields related to your business. Maximum length: 64 characters.
remark20	String	No	Custom data 20. Stores custom fields related to your business. Maximum length: 64 characters.
remark21	String	No	Custom data 21. Stores custom fields related to your business. Maximum length: 64 characters.
remark22	String	No	Custom data 22. Stores custom fields related to your business. Maximum length: 64 characters.
remark23	String	No	Custom data 23. Stores custom fields related to your business. Maximum length: 64 characters.
remark24	String	No	Custom data 24. Stores custom fields related to your business. Maximum length: 64 characters.
remark25	String	No	Custom data 25. Stores custom fields related to your business. Maximum length: 64 characters.
jsonParamStr	String	No	Additional custom fields in JSON string format. The key is the field name and the value is the field content. Example: {"CustomerLevel":3,"Channel":"OfficialWebsite"}.

Callback parameter description

Assume the callback URL provided by the caller is http://aliyun.com/callback. The complete URL during callback is http://aliyun.com/callback?taskId=xxx&timestamp=xxx&aliUid=xxx&signature=xxx&event=xxx, where:

• taskId: The task ID.

• timestamp: The UNIX timestamp at the time of the invocation, in milliseconds.

• aliUid: The Alibaba Cloud account ID of the caller.

• signature: The signature. The caller can use this to verify that the request originates from Alibaba Cloud. Calculation: Perform MD5 + Base64 encryption on taskId=xxx&timestamp=xxx&aliUid=xxx. Note the order. After receiving the callback, the caller can obtain taskId and timestamp from the callback URL. aliUid is the Alibaba Cloud account ID. Compare the self-calculated signature with the signature in the URL to verify consistency. See the Java code example below.

• event: The event name. The caller can use this to determine which event triggered the callback. Valid values: TaskComplete (callback when the task is complete).

public static void signature() {
    long timestamp = System.currentTimeMillis();
    String taskId = "xxx";
    String aliUid = "xxx";
    // Perform MD5 + Base64 encryption on taskId=xxx&timestamp=xxx&aliUid=xxx and place it in the signature field
    String signature;
    try {
        signature = URLEncoder.encode(md5Base64("taskId=" + taskId + "&timestamp=" + timestamp + "&aliUid=" + aliUid), "utf-8");
        System.out.println(signature);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

public static String md5Base64(String str) throws NoSuchAlgorithmException {
    //string encoding must be utf-8
    byte[] utfBytes = str.getBytes(StandardCharsets.UTF_8);
    MessageDigest mdTemp = MessageDigest.getInstance("MD5");
    mdTemp.update(utfBytes);
    byte[] md5Bytes = mdTemp.digest();
    return Base64.encodeBase64String(md5Bytes);
}

Request parameter example

{
    "autoSplit":1,
    "serviceChannelKeywords":[
        "留学",
        "客服老师"
    ],
    "callbackUrl":"https://123.123.com/sca-callback",
    "callList":[
        {
            "schemeTaskConfigId":"589",
            "voiceFileUrl":"https://sca-ccc-test.oss-cn-beijing.aliyuncs.com/****.wav",
            "fileName":"abc.wav",
            "callStartTime":"1584535485856",
            "customerServiceId":"30",
            "customerServiceName":"Aagent",
            "skillGroupId":"34sd24",
            "skillGroupName":"售前技能组",
            "callType":1,
            "callee":188888****,
            "caller":"0102323***",
            "callId":23456457**,
            "business":"售前一组",
            "remark1":"38 节大促"
        }
    ]
}

Request code example

public class sca {
    
    private static String ak = "YOUR_ACCESS_KEY_ID";
    private static String sk = "YOUR_ACCESS_KEY_SECRET";

    private static void uploadAudio() throws Exception {
        String json = "{\n" +
                "    \"autoSplit\":1,\n" +
                "    \"serviceChannelKeywords\":[\n" +
                "        \"留学\",\n" +
                "        \"客服老师\"\n" +
                "    ],\n" +
                "    \"callbackUrl\":\"https://123.123.com/sca-callback\",\n" +
                "    \"callList\":[\n" +
                "        {\n" +
                "            \"schemeTaskConfigId\":\"589\",\n" +
                "            \"voiceFileUrl\":\"https://sc.oss-cn-beijing.aliyuncs.com/****.wav\",\n" +
                "            \"fileName\":\"abc.wav\",\n" +
                "            \"callStartTime\":\"1584535485856\",\n" +
                "            \"customerServiceId\":\"30\",\n" +
                "            \"customerServiceName\":\"Aagent\",\n" +
                "            \"skillGroupId\":\"34sd24\",\n" +
                "            \"skillGroupName\":\"售前技能组\",\n" +
                "            \"callType\":1,\n" +
                "            \"callee\":188888****,\n" +
                "            \"caller\":\"0102323***\",\n" +
                "            \"callId\":23456457**,\n" +
                "            \"business\":\"售前一组\",\n" +
                "            \"remark1\":\"38 节大促\"\n" +
                "        }\n" +
                "    ]\n" +
                "}";


        Config config = new Config();
        config.setAccessKeyId(ak).setAccessKeySecret(sk).setEndpoint("qualitycheck.cn-hangzhou.aliyuncs.com")
                .setRegionId("cn-hangzhou").setProtocol("HTTPS");

        Client client = new Client(config);
        UploadAudioDataRequest result = new UploadAudioDataRequest();

        result.setJsonStr(json);

        UploadAudioDataResponse response = client.uploadAudioData(result);
        System.out.println(JSONObject.toJSONString(response));
    }


    public static void main(String[] args) throws Exception {
        uploadAudio();
    }
}