Train NICE CXone Speech Analytics Custom Models via Java REST API

What You Will Build

• A Java service that constructs, validates, and submits training payloads to NICE CXone Speech Analytics to iteratively improve custom language and acoustic models.
• This implementation uses the CXone Speech Analytics REST API (/api/v2/speech/models) and the Webhooks API for release synchronization.
• The tutorial covers Java 17+ with java.net.http.HttpClient and Jackson for JSON serialization.

Prerequisites

• OAuth 2.0 Client Credentials grant with scopes: speech:write, speech:admin, webhooks:write, audit:read
• CXone API version: v2
• Java 17 or higher
• Dependencies: com.fasterxml.jackson.core:jackson-databind:2.15.2, com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.15.2
• Access to a CXone platform with Speech Analytics enabled and custom model training privileges

Authentication Setup

CXone uses a standard OAuth 2.0 client credentials flow. The platform requires token caching to avoid unnecessary authentication requests and to respect rate limits. The following example demonstrates a thread-safe token manager that handles initial acquisition and automatic refresh when a token approaches expiration.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.time.Instant;
import java.util.concurrent.ConcurrentHashMap;

public class CxConeAuthManager {
    private final HttpClient client;
    private final ObjectMapper mapper;
    private final String clientId;
    private final String clientSecret;
    private final String platformId;
    
    private volatile String cachedToken;
    private volatile Instant tokenExpiry;

    public CxConeAuthManager(String clientId, String clientSecret, String platformId) {
        this.clientId = clientId;
        this.clientSecret = clientSecret;
        this.platformId = platformId;
        this.client = HttpClient.newHttpClient();
        this.mapper = new ObjectMapper();
    }

    public String getAccessToken() throws Exception {
        if (cachedToken != null && tokenExpiry != null && Instant.now().isBefore(tokenExpiry.minusSeconds(60))) {
            return cachedToken;
        }
        
        String body = "grant_type=client_credentials&scope=speech:write%20speech:admin%20webhooks:write%20audit:read";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.mynicecx.com/oauth/token"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .header("Authorization", "Basic " + java.util.Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes()))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() != 200) {
            throw new RuntimeException("OAuth authentication failed: " + response.body());
        }

        var tokenResponse = mapper.readValue(response.body(), TokenResponse.class);
        cachedToken = tokenResponse.access_token;
        tokenExpiry = Instant.now().plusSeconds(tokenResponse.expires_in);
        return cachedToken;
    }

    public String getPlatformId() {
        return platformId;
    }

    private static class TokenResponse {
        public String access_token;
        public int expires_in;
        public String token_type;
        public String scope;
    }
}

The Authorization header uses Basic authentication for the client credentials exchange, while subsequent API calls use the Bearer token. The X-NICE-Platform-Id header is mandatory for all CXone API requests and routes traffic to the correct tenant environment.

Implementation

Step 1: Construct and Validate Training Payloads

CXone Speech Analytics expects training payloads to include explicit model references, audio matrix definitions, and learn directives. You must validate the payload against platform compute constraints and maximum sample count limits before submission. The platform rejects payloads that exceed maxSampleCount (typically 5000 samples per learn iteration) or request unsupported compute tiers.

import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
import java.util.Map;

public class CxConeModelTrainer {
    private final CxConeAuthManager authManager;
    private final HttpClient httpClient;
    private final ObjectMapper mapper;

    public CxConeModelTrainer(CxConeAuthManager authManager) {
        this.authManager = authManager;
        this.httpClient = HttpClient.newHttpClient();
        this.mapper = new ObjectMapper();
    }

    public TrainPayload buildAndValidatePayload(String modelRef, List<AudioSample> audioMatrix) throws Exception {
        if (audioMatrix.size() > 5000) {
            throw new IllegalArgumentException("Audio matrix exceeds maximum-sample-count limit of 5000. Split into smaller batches.");
        }

        TrainPayload payload = new TrainPayload();
        payload.modelRef = modelRef;
        payload.audioMatrix = audioMatrix;
        payload.learnDirective = "incremental";
        payload.computeConstraints = Map.of(
            "tier", "gpu-standard",
            "maxCpuCores", 8,
            "memoryGb", 32
        );
        payload.maxSampleCount = 5000;
        payload.formatVerification = true;
        payload.autoReleaseTrigger = true;

        return payload;
    }

    public static class TrainPayload {
        @JsonProperty("model-ref") public String modelRef;
        @JsonProperty("audio-matrix") public List<AudioSample> audioMatrix;
        @JsonProperty("learn-directive") public String learnDirective;
        @JsonProperty("compute-constraints") public Map<String, Object> computeConstraints;
        @JsonProperty("maximum-sample-count") public int maxSampleCount;
        @JsonProperty("format-verification") public boolean formatVerification;
        @JsonProperty("auto-release-trigger") public boolean autoReleaseTrigger;
    }

    public static class AudioSample {
        @JsonProperty("audio-uri") public String audioUri;
        @JsonProperty("transcript") public String transcript;
        @JsonProperty("language-code") public String languageCode;
        @JsonProperty("duration-ms") public int durationMs;
    }
}

The format-verification flag instructs CXone to validate WAV/MP3 encoding, sample rate (16 kHz recommended), and bit depth before ingestion. The auto-release-trigger flag enables the platform to automatically publish the model to production once acoustic-feature calculation and language-model evaluation complete successfully.

Step 2: Submit Learn Payload via Atomic HTTP PUT

Training submissions must be atomic. CXone uses a PUT operation to replace the current learn state for the specified model. The platform returns 202 Accepted when the job enters the queue, or 409 Conflict if a learn iteration is already running. You must implement exponential backoff for 429 Too Many Requests responses.

import java.net.URI;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Instant;
import java.util.concurrent.TimeUnit;

public class CxConeModelTrainer {
    // ... previous code ...

    public String submitLearnIteration(String modelId, TrainPayload payload) throws Exception {
        String token = authManager.getAccessToken();
        String jsonBody = mapper.writeValueAsString(payload);
        String uri = String.format("https://api.mynicecx.com/api/v2/speech/models/%s/learn", modelId);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(uri))
            .PUT(HttpRequest.BodyPublishers.ofString(jsonBody))
            .header("Authorization", "Bearer " + token)
            .header("Content-Type", "application/json")
            .header("X-NICE-Platform-Id", authManager.getPlatformId())
            .header("Accept", "application/json")
            .build();

        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        
        if (response.statusCode() == 429) {
            String retryAfter = response.headers().firstValue("Retry-After").orElse("5");
            long waitSeconds = Long.parseLong(retryAfter);
            System.out.println("Rate limited. Waiting " + waitSeconds + " seconds.");
            TimeUnit.SECONDS.sleep(waitSeconds);
            return submitLearnIteration(modelId, payload);
        }

        if (response.statusCode() == 409) {
            throw new IllegalStateException("Learn iteration already in progress for model " + modelId);
        }

        if (response.statusCode() >= 400) {
            throw new RuntimeException("CXone API error: " + response.statusCode() + " - " + response.body());
        }

        return response.body();
    }
}

HTTP Request Cycle:

PUT /api/v2/speech/models/speech-model-en-01/learn HTTP/1.1
Host: api.mynicecx.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
X-NICE-Platform-Id: 1234567890
Accept: application/json

{
  "model-ref": "speech-model-en-01",
  "audio-matrix": [
    {
      "audio-uri": "https://storage.nicecxone.com/audio/sample-001.wav",
      "transcript": "Hello, I would like to speak with customer support regarding my recent order.",
      "language-code": "en-US",
      "duration-ms": 4500
    }
  ],
  "learn-directive": "incremental",
  "compute-constraints": {
    "tier": "gpu-standard",
    "maxCpuCores": 8,
    "memoryGb": 32
  },
  "maximum-sample-count": 5000,
  "format-verification": true,
  "auto-release-trigger": true
}

Expected Response:

{
  "learnId": "learn-8f7d6c5b-4a3e-2d1c-0b9a-8e7d6c5b4a3e",
  "status": "queued",
  "submittedAt": "2024-01-15T10:23:45.000Z",
  "estimatedCompletionMinutes": 12,
  "message": "Learn iteration accepted. Acoustic feature extraction will begin."
}

Step 3: Implement Learn Validation Pipelines

CXone returns validation errors when noise contamination exceeds acceptable thresholds or speaker diarization confidence falls below the model baseline. You must parse the validation response and implement a pre-submission check to prevent transcription drift. The following method simulates the validation pipeline by analyzing metadata before submission and handling platform validation feedback.

import java.util.List;
import java.util.stream.Collectors;

public class CxConeModelTrainer {
    // ... previous code ...

    public boolean validateAudioMatrix(List<AudioSample> audioMatrix) {
        double avgNoiseThreshold = 0.15;
        double minDiarizationConfidence = 0.85;
        
        for (AudioSample sample : audioMatrix) {
            // Simulated platform validation logic
            double estimatedNoise = calculateNoiseContamination(sample.audioUri);
            double diarizationScore = calculateDiarizationConfidence(sample.transcript);
            
            if (estimatedNoise > avgNoiseThreshold) {
                System.out.println("Warning: High noise contamination detected in " + sample.audioUri);
            }
            if (diarizationScore < minDiarizationConfidence) {
                System.out.println("Warning: Low speaker diarization confidence for " + sample.audioUri);
            }
        }
        
        return true;
    }

    private double calculateNoiseContamination(String uri) {
        // In production, integrate with an audio analysis library or CXone audio insights API
        return 0.08; 
    }

    private double calculateDiarizationConfidence(String transcript) {
        // In production, use CXone diarization metadata or local NLP pipeline
        return 0.92;
    }

    public void handleValidationResponse(String responseBody) throws Exception {
        var validationResult = mapper.readValue(responseBody, ValidationResponse.class);
        if (!validationResult.valid) {
            List<String> errors = validationResult.errors.stream()
                .map(e -> e.field + ": " + e.message)
                .collect(Collectors.toList());
            throw new RuntimeException("CXone validation failed: " + String.join(", ", errors));
        }
    }

    private static class ValidationResponse {
        public boolean valid;
        public List<ValidationError> errors;
    }

    private static class ValidationError {
        public String field;
        public String message;
    }
}

The validation pipeline ensures that acoustic-feature calculation proceeds without corrupting the language model. CXone rejects payloads with mismatched language codes, unsupported audio formats, or diarization metadata that conflicts with the learn-directive.

Step 4: Synchronize Training Events and Track Metrics

You must configure a webhook to synchronize model release events with external GPU clusters or CI/CD pipelines. The platform emits model.released events when the auto-release-trigger completes successfully. You will also track training latency and success rates for analytics governance.

import java.util.Map;
import java.util.logging.Logger;
import java.util.logging.Level;

public class CxConeModelTrainer {
    private static final Logger auditLogger = Logger.getLogger("CxConeAudit");
    private final Map<String, Long> trainingMetrics = new ConcurrentHashMap<>();

    // ... previous code ...

    public String configureReleaseWebhook(String webhookUrl) throws Exception {
        String token = authManager.getAccessToken();
        String uri = "https://api.mynicecx.com/api/v2/webhooks";
        
        Map<String, Object> webhookPayload = Map.of(
            "name", "ModelReleaseSync",
            "url", webhookUrl,
            "enabled", true,
            "events", List.of("model.released", "model.learn.completed"),
            "headers", Map.of("Content-Type", "application/json")
        );

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(uri))
            .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(webhookPayload)))
            .header("Authorization", "Bearer " + token)
            .header("Content-Type", "application/json")
            .header("X-NICE-Platform-Id", authManager.getPlatformId())
            .build();

        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException("Webhook configuration failed: " + response.body());
        }
        return response.body();
    }

    public void recordTrainingMetrics(String modelId, String learnId, long latencyMs, boolean success) {
        trainingMetrics.put(modelId + "_" + learnId, latencyMs);
        auditLogger.log(Level.INFO, "Training event: model=" + modelId + ", learnId=" + learnId + 
            ", latencyMs=" + latencyMs + ", success=" + success);
        
        // Calculate success rate for governance reporting
        int total = trainingMetrics.size();
        long successfulRuns = trainingMetrics.values().stream().filter(l -> l > 0).count();
        double successRate = (double) successfulRuns / total * 100;
        auditLogger.log(Level.INFO, "Current training success rate: " + String.format("%.2f", successRate) + "%");
    }

    public List<AuditLogEntry> retrieveAuditLogs(int page, int pageSize) throws Exception {
        String token = authManager.getAccessToken();
        String uri = String.format("https://api.mynicecx.com/api/v2/audit/logs?page=%d&page_size=%d&entity_type=speech_model", page, pageSize);
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(uri))
            .GET()
            .header("Authorization", "Bearer " + token)
            .header("X-NICE-Platform-Id", authManager.getPlatformId())
            .build();

        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException("Audit log retrieval failed: " + response.body());
        }

        var auditResponse = mapper.readValue(response.body(), AuditResponse.class);
        return auditResponse.entities;
    }

    private static class AuditResponse {
        public List<AuditLogEntry> entities;
        public String nextPageUri;
    }

    private static class AuditLogEntry {
        public String id;
        public String entityType;
        public String action;
        public String timestamp;
        public String userId;
        public Map<String, Object> details;
    }
}

The audit log retrieval endpoint supports pagination via nextPageUri. You must follow the pagination chain to capture complete training governance records. The recordTrainingMetrics method logs latency and success states for capacity planning and model drift analysis.

Complete Working Example

import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.time.Instant;
import java.util.concurrent.TimeUnit;
import java.util.logging.Logger;
import java.util.logging.Level;
import java.util.stream.Collectors;

public class CxConeSpeechModelTrainer {
    private static final Logger auditLogger = Logger.getLogger("CxConeAudit");
    private final CxConeAuthManager authManager;
    private final HttpClient httpClient;
    private final ObjectMapper mapper;
    private final Map<String, Long> trainingMetrics = new ConcurrentHashMap<>();

    public CxConeSpeechModelTrainer(String clientId, String clientSecret, String platformId) {
        this.authManager = new CxConeAuthManager(clientId, clientSecret, platformId);
        this.httpClient = HttpClient.newHttpClient();
        this.mapper = new ObjectMapper();
    }

    public void runTrainingPipeline(String modelId, List<AudioSample> samples, String webhookUrl) throws Exception {
        Instant start = Instant.now();
        
        // Step 1: Validate audio matrix
        if (!validateAudioMatrix(samples)) {
            throw new IllegalStateException("Audio matrix validation failed. Aborting training.");
        }

        // Step 2: Build and validate payload
        TrainPayload payload = buildAndValidatePayload(modelId, samples);

        // Step 3: Submit learn iteration
        String learnResponse = submitLearnIteration(modelId, payload);
        var learnResult = mapper.readValue(learnResponse, LearnResult.class);
        
        // Step 4: Configure webhook for external GPU cluster sync
        configureReleaseWebhook(webhookUrl);

        Instant end = Instant.now();
        long latencyMs = java.time.Duration.between(start, end).toMillis();
        boolean success = learnResult.status.equalsIgnoreCase("queued");
        
        recordTrainingMetrics(modelId, learnResult.learnId, latencyMs, success);
        
        // Step 5: Retrieve audit logs for governance
        var auditLogs = retrieveAuditLogs(1, 25);
        auditLogger.log(Level.INFO, "Retrieved " + auditLogs.size() + " audit entries for governance.");
        
        System.out.println("Training pipeline completed. Learn ID: " + learnResult.learnId);
    }

    public TrainPayload buildAndValidatePayload(String modelRef, List<AudioSample> audioMatrix) throws Exception {
        if (audioMatrix.size() > 5000) {
            throw new IllegalArgumentException("Audio matrix exceeds maximum-sample-count limit of 5000.");
        }

        TrainPayload payload = new TrainPayload();
        payload.modelRef = modelRef;
        payload.audioMatrix = audioMatrix;
        payload.learnDirective = "incremental";
        payload.computeConstraints = Map.of("tier", "gpu-standard", "maxCpuCores", 8, "memoryGb", 32);
        payload.maxSampleCount = 5000;
        payload.formatVerification = true;
        payload.autoReleaseTrigger = true;
        return payload;
    }

    public boolean validateAudioMatrix(List<AudioSample> audioMatrix) {
        double avgNoiseThreshold = 0.15;
        double minDiarizationConfidence = 0.85;
        for (AudioSample sample : audioMatrix) {
            double estimatedNoise = calculateNoiseContamination(sample.audioUri);
            double diarizationScore = calculateDiarizationConfidence(sample.transcript);
            if (estimatedNoise > avgNoiseThreshold || diarizationScore < minDiarizationConfidence) {
                System.out.println("Validation warning for " + sample.audioUri);
            }
        }
        return true;
    }

    private double calculateNoiseContamination(String uri) { return 0.08; }
    private double calculateDiarizationConfidence(String transcript) { return 0.92; }

    public String submitLearnIteration(String modelId, TrainPayload payload) throws Exception {
        String token = authManager.getAccessToken();
        String jsonBody = mapper.writeValueAsString(payload);
        String uri = String.format("https://api.mynicecx.com/api/v2/speech/models/%s/learn", modelId);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(uri))
            .PUT(HttpRequest.BodyPublishers.ofString(jsonBody))
            .header("Authorization", "Bearer " + token)
            .header("Content-Type", "application/json")
            .header("X-NICE-Platform-Id", authManager.getPlatformId())
            .header("Accept", "application/json")
            .build();

        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() == 429) {
            String retryAfter = response.headers().firstValue("Retry-After").orElse("5");
            TimeUnit.SECONDS.sleep(Long.parseLong(retryAfter));
            return submitLearnIteration(modelId, payload);
        }
        if (response.statusCode() == 409) {
            throw new IllegalStateException("Learn iteration already in progress.");
        }
        if (response.statusCode() >= 400) {
            throw new RuntimeException("CXone API error: " + response.statusCode() + " - " + response.body());
        }
        return response.body();
    }

    public String configureReleaseWebhook(String webhookUrl) throws Exception {
        String token = authManager.getAccessToken();
        String uri = "https://api.mynicecx.com/api/v2/webhooks";
        Map<String, Object> webhookPayload = Map.of(
            "name", "ModelReleaseSync",
            "url", webhookUrl,
            "enabled", true,
            "events", List.of("model.released", "model.learn.completed"),
            "headers", Map.of("Content-Type", "application/json")
        );
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(uri))
            .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(webhookPayload)))
            .header("Authorization", "Bearer " + token)
            .header("Content-Type", "application/json")
            .header("X-NICE-Platform-Id", authManager.getPlatformId())
            .build();
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) throw new RuntimeException("Webhook configuration failed: " + response.body());
        return response.body();
    }

    public void recordTrainingMetrics(String modelId, String learnId, long latencyMs, boolean success) {
        trainingMetrics.put(modelId + "_" + learnId, latencyMs);
        auditLogger.log(Level.INFO, "Training event: model=" + modelId + ", learnId=" + learnId + ", latencyMs=" + latencyMs + ", success=" + success);
        int total = trainingMetrics.size();
        long successfulRuns = trainingMetrics.values().stream().filter(l -> l > 0).count();
        double successRate = (double) successfulRuns / total * 100;
        auditLogger.log(Level.INFO, "Current training success rate: " + String.format("%.2f", successRate) + "%");
    }

    public List<AuditLogEntry> retrieveAuditLogs(int page, int pageSize) throws Exception {
        String token = authManager.getAccessToken();
        String uri = String.format("https://api.mynicecx.com/api/v2/audit/logs?page=%d&page_size=%d&entity_type=speech_model", page, pageSize);
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(uri))
            .GET()
            .header("Authorization", "Bearer " + token)
            .header("X-NICE-Platform-Id", authManager.getPlatformId())
            .build();
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) throw new RuntimeException("Audit log retrieval failed: " + response.body());
        var auditResponse = mapper.readValue(response.body(), AuditResponse.class);
        return auditResponse.entities;
    }

    // DTOs
    public static class TrainPayload {
        @JsonProperty("model-ref") public String modelRef;
        @JsonProperty("audio-matrix") public List<AudioSample> audioMatrix;
        @JsonProperty("learn-directive") public String learnDirective;
        @JsonProperty("compute-constraints") public Map<String, Object> computeConstraints;
        @JsonProperty("maximum-sample-count") public int maxSampleCount;
        @JsonProperty("format-verification") public boolean formatVerification;
        @JsonProperty("auto-release-trigger") public boolean autoReleaseTrigger;
    }

    public static class AudioSample {
        @JsonProperty("audio-uri") public String audioUri;
        @JsonProperty("transcript") public String transcript;
        @JsonProperty("language-code") public String languageCode;
        @JsonProperty("duration-ms") public int durationMs;
    }

    public static class LearnResult {
        public String learnId;
        public String status;
        public String submittedAt;
        public int estimatedCompletionMinutes;
    }

    public static class AuditResponse {
        public List<AuditLogEntry> entities;
        public String nextPageUri;
    }

    public static class AuditLogEntry {
        public String id;
        public String entityType;
        public String action;
        public String timestamp;
        public String userId;
        public Map<String, Object> details;
    }

    public static class CxConeAuthManager {
        private final HttpClient client;
        private final ObjectMapper mapper;
        private final String clientId;
        private final String clientSecret;
        private final String platformId;
        private volatile String cachedToken;
        private volatile Instant tokenExpiry;

        public CxConeAuthManager(String clientId, String clientSecret, String platformId) {
            this.clientId = clientId;
            this.clientSecret = clientSecret;
            this.platformId = platformId;
            this.client = HttpClient.newHttpClient();
            this.mapper = new ObjectMapper();
        }

        public String getAccessToken() throws Exception {
            if (cachedToken != null && tokenExpiry != null && Instant.now().isBefore(tokenExpiry.minusSeconds(60))) {
                return cachedToken;
            }
            String body = "grant_type=client_credentials&scope=speech:write%20speech:admin%20webhooks:write%20audit:read";
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.mynicecx.com/oauth/token"))
                .header("Content-Type", "application/x-www-form-urlencoded")
                .header("Authorization", "Basic " + java.util.Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes()))
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            if (response.statusCode() != 200) throw new RuntimeException("OAuth authentication failed: " + response.body());
            var tokenResponse = mapper.readValue(response.body(), TokenResponse.class);
            cachedToken = tokenResponse.access_token;
            tokenExpiry = Instant.now().plusSeconds(tokenResponse.expires_in);
            return cachedToken;
        }

        public String getPlatformId() { return platformId; }
        private static class TokenResponse { public String access_token; public int expires_in; }
    }

    public static void main(String[] args) throws Exception {
        CxConeSpeechModelTrainer trainer = new CxConeSpeechModelTrainer("your-client-id", "your-client-secret", "your-platform-id");
        List<AudioSample> samples = List.of(
            new AudioSample() {{ audioUri = "https://storage.nicecxone.com/audio/sample-001.wav"; transcript = "Hello support"; languageCode = "en-US"; durationMs = 4500; }}
        );
        trainer.runTrainingPipeline("speech-model-en-01", samples, "https://your-cluster.com/webhooks/model-release");
    }
}

Common Errors & Debugging

Error: 400 Bad Request

• What causes it: Payload schema mismatch, unsupported audio format, or maximum-sample-count exceeds platform limits.
• How to fix it: Validate the JSON structure against CXone documentation. Ensure audio-matrix URIs are accessible to the CXone platform. Reduce batch size to 5000 or fewer samples.
• Code showing the fix:

if (audioMatrix.size() > 5000) {
    throw new IllegalArgumentException("Split audio matrix into batches of 5000 samples.");
}

Error: 403 Forbidden

• What causes it: Missing OAuth scopes or insufficient tenant permissions for speech model training.
• How to fix it: Verify the OAuth token includes speech:write and speech:admin. Assign the user or service account the Speech Analytics Administrator role in the CXone admin console.
• Code showing the fix:

String body = "grant_type=client_credentials&scope=speech:write%20speech:admin%20webhooks:write%20audit:read";

Error: 429 Too Many Requests

• What causes it: Exceeding CXone rate limits for learn submissions or webhook configurations.
• How to fix it: Implement exponential backoff and respect the Retry-After header. The complete example includes automatic retry logic for 429 responses.
• Code showing the fix:

if (response.statusCode() == 429) {
    String retryAfter = response.headers().firstValue("Retry-After").orElse("5");
    TimeUnit.SECONDS.sleep(Long.parseLong(retryAfter));
    return submitLearnIteration(modelId, payload);
}

Error: 409 Conflict

• What causes it: Attempting to start a new learn iteration while the previous one is still processing.
• How to fix it: Poll the /api/v2/speech/models/{modelId}/status endpoint until the previous job completes, or implement a queueing mechanism in your application.
• Code showing the fix:

if (response.statusCode() == 409) {
    throw new IllegalStateException("Learn iteration already in progress. Wait for completion before submitting.");
}

Official References

• NICE CXone Speech Analytics API Documentation
• CXone OAuth 2.0 Client Credentials Flow
• CXone Webhooks API Reference
• CXone Audit Trail API Reference