Azure Communication Callautomation Java

1---
2name: azure-communication-callautomation-java
3description: Build call automation workflows with Azure Communication Services Call Automation Java SDK. Use when implementing IVR systems, call routing, call recording, DTMF recognition, text-to-speech, or AI-powered call flows.
4package: com.azure:azure-communication-callautomation
5---
6 
7# Azure Communication Call Automation (Java)
8 
9Build server-side call automation workflows including IVR systems, call routing, recording, and AI-powered interactions.
10 
11## Installation
12 
13```xml
14<dependency>
15    <groupId>com.azure</groupId>
16    <artifactId>azure-communication-callautomation</artifactId>
17    <version>1.6.0</version>
18</dependency>
19```
20 
21## Client Creation
22 
23```java
24import com.azure.communication.callautomation.CallAutomationClient;
25import com.azure.communication.callautomation.CallAutomationClientBuilder;
26import com.azure.identity.DefaultAzureCredentialBuilder;
27 
28// With DefaultAzureCredential
29CallAutomationClient client = new CallAutomationClientBuilder()
30    .endpoint("https://<resource>.communication.azure.com")
31    .credential(new DefaultAzureCredentialBuilder().build())
32    .buildClient();
33 
34// With connection string
35CallAutomationClient client = new CallAutomationClientBuilder()
36    .connectionString("<connection-string>")
37    .buildClient();
38```
39 
40## Key Concepts
41 
42| Class | Purpose |
43|-------|---------|
44| `CallAutomationClient` | Make calls, answer/reject incoming calls, redirect calls |
45| `CallConnection` | Actions in established calls (add participants, terminate) |
46| `CallMedia` | Media operations (play audio, recognize DTMF/speech) |
47| `CallRecording` | Start/stop/pause recording |
48| `CallAutomationEventParser` | Parse webhook events from ACS |
49 
50## Create Outbound Call
51 
52```java
53import com.azure.communication.callautomation.models.*;
54import com.azure.communication.common.CommunicationUserIdentifier;
55import com.azure.communication.common.PhoneNumberIdentifier;
56 
57// Call to PSTN number
58PhoneNumberIdentifier target = new PhoneNumberIdentifier("+14255551234");
59PhoneNumberIdentifier caller = new PhoneNumberIdentifier("+14255550100");
60 
61CreateCallOptions options = new CreateCallOptions(
62    new CommunicationUserIdentifier("<user-id>"),  // Source
63    List.of(target))                                // Targets
64    .setSourceCallerId(caller)
65    .setCallbackUrl("https://your-app.com/api/callbacks");
66 
67CreateCallResult result = client.createCall(options);
68String callConnectionId = result.getCallConnectionProperties().getCallConnectionId();
69```
70 
71## Answer Incoming Call
72 
73```java
74// From Event Grid webhook - IncomingCall event
75String incomingCallContext = "<incoming-call-context-from-event>";
76 
77AnswerCallOptions options = new AnswerCallOptions(
78    incomingCallContext,
79    "https://your-app.com/api/callbacks");
80 
81AnswerCallResult result = client.answerCall(options);
82CallConnection callConnection = result.getCallConnection();
83```
84 
85## Play Audio (Text-to-Speech)
86 
87```java
88CallConnection callConnection = client.getCallConnection(callConnectionId);
89CallMedia callMedia = callConnection.getCallMedia();
90 
91// Play text-to-speech
92TextSource textSource = new TextSource()
93    .setText("Welcome to Contoso. Press 1 for sales, 2 for support.")
94    .setVoiceName("en-US-JennyNeural");
95 
96PlayOptions playOptions = new PlayOptions(
97    List.of(textSource),
98    List.of(new CommunicationUserIdentifier("<target-user>")));
99 
100callMedia.play(playOptions);
101 
102// Play audio file
103FileSource fileSource = new FileSource()
104    .setUrl("https://storage.blob.core.windows.net/audio/greeting.wav");
105 
106callMedia.play(new PlayOptions(List.of(fileSource), List.of(target)));
107```
108 
109## Recognize DTMF Input
110 
111```java
112// Recognize DTMF tones
113DtmfTone stopTones = DtmfTone.POUND;
114 
115CallMediaRecognizeDtmfOptions recognizeOptions = new CallMediaRecognizeDtmfOptions(
116    new CommunicationUserIdentifier("<target-user>"),
117    5)  // Max tones to collect
118    .setInterToneTimeout(Duration.ofSeconds(5))
119    .setStopTones(List.of(stopTones))
120    .setInitialSilenceTimeout(Duration.ofSeconds(15))
121    .setPlayPrompt(new TextSource().setText("Enter your account number followed by pound."));
122 
123callMedia.startRecognizing(recognizeOptions);
124```
125 
126## Recognize Speech
127 
128```java
129// Speech recognition with AI
130CallMediaRecognizeSpeechOptions speechOptions = new CallMediaRecognizeSpeechOptions(
131    new CommunicationUserIdentifier("<target-user>"))
132    .setEndSilenceTimeout(Duration.ofSeconds(2))
133    .setSpeechLanguage("en-US")
134    .setPlayPrompt(new TextSource().setText("How can I help you today?"));
135 
136callMedia.startRecognizing(speechOptions);
137```
138 
139## Call Recording
140 
141```java
142CallRecording callRecording = client.getCallRecording();
143 
144// Start recording
145StartRecordingOptions recordingOptions = new StartRecordingOptions(
146    new ServerCallLocator("<server-call-id>"))
147    .setRecordingChannel(RecordingChannel.MIXED)
148    .setRecordingContent(RecordingContent.AUDIO_VIDEO)
149    .setRecordingFormat(RecordingFormat.MP4);
150 
151RecordingStateResult recordingResult = callRecording.start(recordingOptions);
152String recordingId = recordingResult.getRecordingId();
153 
154// Pause/resume/stop
155callRecording.pause(recordingId);
156callRecording.resume(recordingId);
157callRecording.stop(recordingId);
158 
159// Download recording (after RecordingFileStatusUpdated event)
160callRecording.downloadTo(recordingUrl, Paths.get("recording.mp4"));
161```
162 
163## Add Participant to Call
164 
165```java
166CallConnection callConnection = client.getCallConnection(callConnectionId);
167 
168CommunicationUserIdentifier participant = new CommunicationUserIdentifier("<user-id>");
169AddParticipantOptions addOptions = new AddParticipantOptions(participant)
170    .setInvitationTimeout(Duration.ofSeconds(30));
171 
172AddParticipantResult result = callConnection.addParticipant(addOptions);
173```
174 
175## Transfer Call
176 
177```java
178// Blind transfer
179PhoneNumberIdentifier transferTarget = new PhoneNumberIdentifier("+14255559999");
180TransferCallToParticipantResult result = callConnection.transferCallToParticipant(transferTarget);
181```
182 
183## Handle Events (Webhook)
184 
185```java
186import com.azure.communication.callautomation.CallAutomationEventParser;
187import com.azure.communication.callautomation.models.events.*;
188 
189// In your webhook endpoint
190public void handleCallback(String requestBody) {
191    List<CallAutomationEventBase> events = CallAutomationEventParser.parseEvents(requestBody);
192    
193    for (CallAutomationEventBase event : events) {
194        if (event instanceof CallConnected) {
195            CallConnected connected = (CallConnected) event;
196            System.out.println("Call connected: " + connected.getCallConnectionId());
197        } else if (event instanceof RecognizeCompleted) {
198            RecognizeCompleted recognized = (RecognizeCompleted) event;
199            // Handle DTMF or speech recognition result
200            DtmfResult dtmfResult = (DtmfResult) recognized.getRecognizeResult();
201            String tones = dtmfResult.getTones().stream()
202                .map(DtmfTone::toString)
203                .collect(Collectors.joining());
204            System.out.println("DTMF received: " + tones);
205        } else if (event instanceof PlayCompleted) {
206            System.out.println("Audio playback completed");
207        } else if (event instanceof CallDisconnected) {
208            System.out.println("Call ended");
209        }
210    }
211}
212```
213 
214## Hang Up Call
215 
216```java
217// Hang up for all participants
218callConnection.hangUp(true);
219 
220// Hang up only this leg
221callConnection.hangUp(false);
222```
223 
224## Error Handling
225 
226```java
227import com.azure.core.exception.HttpResponseException;
228 
229try {
230    client.answerCall(options);
231} catch (HttpResponseException e) {
232    if (e.getResponse().getStatusCode() == 404) {
233        System.out.println("Call not found or already ended");
234    } else if (e.getResponse().getStatusCode() == 400) {
235        System.out.println("Invalid request: " + e.getMessage());
236    }
237}
238```
239 
240## Environment Variables
241 
242```bash
243AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com
244AZURE_COMMUNICATION_CONNECTION_STRING=endpoint=https://...;accesskey=...
245CALLBACK_BASE_URL=https://your-app.com/api/callbacks
246```
247 
248## Trigger Phrases
249 
250- "call automation Java", "IVR Java", "interactive voice response"
251- "call recording Java", "DTMF recognition Java"
252- "text to speech call", "speech recognition call"
253- "answer incoming call", "transfer call Java"
254- "Azure Communication Services call automation"
255