Azure Communication Call Automation (Java)

Build server-side call automation workflows including IVR systems, call routing, recording, and AI-powered interactions.

Installation

<dependency> <groupId>com.azure</groupId> <artifactId>azure-communication-callautomation</artifactId> <version>1.6.0</version> </dependency>

Client Creation

import com.azure.communication.callautomation.CallAutomationClient; import com.azure.communication.callautomation.CallAutomationClientBuilder; import com.azure.identity.DefaultAzureCredentialBuilder;

// With DefaultAzureCredential CallAutomationClient client = new CallAutomationClientBuilder() .endpoint("https://<resource>.communication.azure.com") .credential(new DefaultAzureCredentialBuilder().build()) .buildClient();

// With connection string CallAutomationClient client = new CallAutomationClientBuilder() .connectionString("<connection-string>") .buildClient();

Key Concepts

Class Purpose

CallAutomationClient

Make calls, answer/reject incoming calls, redirect calls

CallConnection

Actions in established calls (add participants, terminate)

CallMedia

Media operations (play audio, recognize DTMF/speech)

CallRecording

Start/stop/pause recording

CallAutomationEventParser

Parse webhook events from ACS

Create Outbound Call

import com.azure.communication.callautomation.models.*; import com.azure.communication.common.CommunicationUserIdentifier; import com.azure.communication.common.PhoneNumberIdentifier;

// Call to PSTN number PhoneNumberIdentifier target = new PhoneNumberIdentifier("+14255551234"); PhoneNumberIdentifier caller = new PhoneNumberIdentifier("+14255550100");

CreateCallOptions options = new CreateCallOptions( new CommunicationUserIdentifier("<user-id>"), // Source List.of(target)) // Targets .setSourceCallerId(caller) .setCallbackUrl("https://your-app.com/api/callbacks");

CreateCallResult result = client.createCall(options); String callConnectionId = result.getCallConnectionProperties().getCallConnectionId();

Answer Incoming Call

// From Event Grid webhook - IncomingCall event String incomingCallContext = "<incoming-call-context-from-event>";

AnswerCallOptions options = new AnswerCallOptions( incomingCallContext, "https://your-app.com/api/callbacks");

AnswerCallResult result = client.answerCall(options); CallConnection callConnection = result.getCallConnection();

Play Audio (Text-to-Speech)

CallConnection callConnection = client.getCallConnection(callConnectionId); CallMedia callMedia = callConnection.getCallMedia();

// Play text-to-speech TextSource textSource = new TextSource() .setText("Welcome to Contoso. Press 1 for sales, 2 for support.") .setVoiceName("en-US-JennyNeural");

PlayOptions playOptions = new PlayOptions( List.of(textSource), List.of(new CommunicationUserIdentifier("<target-user>")));

callMedia.play(playOptions);

// Play audio file FileSource fileSource = new FileSource() .setUrl("https://storage.blob.core.windows.net/audio/greeting.wav");

callMedia.play(new PlayOptions(List.of(fileSource), List.of(target)));

Recognize DTMF Input

// Recognize DTMF tones DtmfTone stopTones = DtmfTone.POUND;

CallMediaRecognizeDtmfOptions recognizeOptions = new CallMediaRecognizeDtmfOptions( new CommunicationUserIdentifier("<target-user>"), 5) // Max tones to collect .setInterToneTimeout(Duration.ofSeconds(5)) .setStopTones(List.of(stopTones)) .setInitialSilenceTimeout(Duration.ofSeconds(15)) .setPlayPrompt(new TextSource().setText("Enter your account number followed by pound."));

callMedia.startRecognizing(recognizeOptions);

Recognize Speech

// Speech recognition with AI CallMediaRecognizeSpeechOptions speechOptions = new CallMediaRecognizeSpeechOptions( new CommunicationUserIdentifier("<target-user>")) .setEndSilenceTimeout(Duration.ofSeconds(2)) .setSpeechLanguage("en-US") .setPlayPrompt(new TextSource().setText("How can I help you today?"));

callMedia.startRecognizing(speechOptions);

Call Recording

CallRecording callRecording = client.getCallRecording();

// Start recording StartRecordingOptions recordingOptions = new StartRecordingOptions( new ServerCallLocator("<server-call-id>")) .setRecordingChannel(RecordingChannel.MIXED) .setRecordingContent(RecordingContent.AUDIO_VIDEO) .setRecordingFormat(RecordingFormat.MP4);

RecordingStateResult recordingResult = callRecording.start(recordingOptions); String recordingId = recordingResult.getRecordingId();

// Pause/resume/stop callRecording.pause(recordingId); callRecording.resume(recordingId); callRecording.stop(recordingId);

// Download recording (after RecordingFileStatusUpdated event) callRecording.downloadTo(recordingUrl, Paths.get("recording.mp4"));

Add Participant to Call

CallConnection callConnection = client.getCallConnection(callConnectionId);

CommunicationUserIdentifier participant = new CommunicationUserIdentifier("<user-id>"); AddParticipantOptions addOptions = new AddParticipantOptions(participant) .setInvitationTimeout(Duration.ofSeconds(30));

AddParticipantResult result = callConnection.addParticipant(addOptions);

Transfer Call

// Blind transfer PhoneNumberIdentifier transferTarget = new PhoneNumberIdentifier("+14255559999"); TransferCallToParticipantResult result = callConnection.transferCallToParticipant(transferTarget);

Handle Events (Webhook)

import com.azure.communication.callautomation.CallAutomationEventParser; import com.azure.communication.callautomation.models.events.*;

// In your webhook endpoint public void handleCallback(String requestBody) { List<CallAutomationEventBase> events = CallAutomationEventParser.parseEvents(requestBody);

for (CallAutomationEventBase event : events) {
    if (event instanceof CallConnected) {
        CallConnected connected = (CallConnected) event;
        System.out.println("Call connected: " + connected.getCallConnectionId());
    } else if (event instanceof RecognizeCompleted) {
        RecognizeCompleted recognized = (RecognizeCompleted) event;
        // Handle DTMF or speech recognition result
        DtmfResult dtmfResult = (DtmfResult) recognized.getRecognizeResult();
        String tones = dtmfResult.getTones().stream()
            .map(DtmfTone::toString)
            .collect(Collectors.joining());
        System.out.println("DTMF received: " + tones);
    } else if (event instanceof PlayCompleted) {
        System.out.println("Audio playback completed");
    } else if (event instanceof CallDisconnected) {
        System.out.println("Call ended");
    }
}

}

Hang Up Call

// Hang up for all participants callConnection.hangUp(true);

// Hang up only this leg callConnection.hangUp(false);

Error Handling

import com.azure.core.exception.HttpResponseException;

try { client.answerCall(options); } catch (HttpResponseException e) { if (e.getResponse().getStatusCode() == 404) { System.out.println("Call not found or already ended"); } else if (e.getResponse().getStatusCode() == 400) { System.out.println("Invalid request: " + e.getMessage()); } }

Environment Variables

AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com AZURE_COMMUNICATION_CONNECTION_STRING=endpoint=https://...;accesskey=... CALLBACK_BASE_URL=https://your-app.com/api/callbacks

Trigger Phrases

• "call automation Java", "IVR Java", "interactive voice response"

• "call recording Java", "DTMF recognition Java"

• "text to speech call", "speech recognition call"

• "answer incoming call", "transfer call Java"

• "Azure Communication Services call automation"