answer call and play hold music

Question

answer call and play hold music

Debajyoti Sarma 0

We are using Call Automation and Job Router together to manage our call jobs.

When we get Microsoft.Communication.IncomingCall event from azure event grid webhook, we do following

Answer the call

   const { callConnection } = await callAutomationClient.answerCall(incomingCallContext, ACS_EVENT_GRID_BASE_URL);
   const { callConnectionId } = callConnection;

sleep for 5s

   await new Promise((resolve) => setTimeout(resolve, 5000));

play hold music

   const callConnection = await callAutomationClient.getCallConnection(callConnectionId);
       
   const callConnectionProperties = await  callConnection.getCallConnectionProperties();
       
   const playSource = {
         url: audioFileUrl,
         kind: "fileSource"
   };
   
   // Configure play options to loop the audio
   const playOptions = {
         loop: true
   };
   
   await callConnection
         .getCallMedia()
         .play([playSource], [ callConnectionProperties.source ], playOptions);

If we run Step 1 and 3 consecutively without sleep then getCallConnection is not able to find the callConnection. I think azure takes time to distribute the info about the call, so a sleep of 5s is needed.

We even tried to reuse callConnection object but that also gives problem in getCallConnectionProperties

Due to this after first ring on the incoming call, we have to wait for around 10-15s to listen to hold music of audioFileUrl.

Questions

Is there a way to optimize this by removing sleep? Relying on another event to detect call answered is not an option because we are doing further processing in IncomingCall event.
Is there a way to pass audioFileUrl while answering the call?

Bhargavi Naragani 7,445 Reputation points Microsoft External Staff Moderator

2025-08-11T10:29:28.63+00:00
Hi Debajyoti Sarma,

The ACS Call Automation model is event-driven and eventually consistent. Even though answerCall returns a connection ID, the underlying system needs time to register and make that connection visible for subsequent actions like media playback. So right after answering, getCallConnection(...) may not yet locate the active call.

Recent ACS updates introduced a playStarted event. This lets you start hold music and then know precisely when the play action has been recognized by the backend. You can:

Immediately after answering, call play(...) with loop=true to start hold music.

Then listen for the playStarted event to confirm that hold music is actually playing rather than guessing via timing.

This avoids the need to poll or sleep. The API now supports looping hold music, barge-in, and includes events to show when playback begins https://learn.microsoft.com/en-us/azure/communication-services/concepts/call-automation/play-action

Skip the extra getCallConnection(...) call, you already have the callConnection object from the answerCall() call. Use it directly to perform the play() operation, assuming the SDK instance is still valid. That avoids re-querying ACS's backend state.

ACS now also supports explicitly holding participants, which inherently plays hold music if configured https://learn.microsoft.com/en-us/azure/communication-services/whats-new

Hope this helps, if you have any further concerns or queries, please feel free to reach out to us.

Debajyoti Sarma 0

Hi,

Immediately after answering, if I call play(...) with loop=true to start hold music I get following error and hold music doesn't get played. This I tried without extra getCallConnection(...)

RestError: Call not found.    
at handleErrorResponse (/Users/deba.jyoti/code/voice-orchestrator-be/node_modules/@azure/core-client/dist/commonjs/deserializationPolicy.js:148:19)
at deserializeResponseBody (/Users/deba.jyoti/code/voice-orchestrator-be/node_modules/@azure/core-client/dist/commonjs/deserializationPolicy.js:83:45)   
at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

But If I add sleep before play it works fine.

Bhargavi Naragani 7,445 Reputation points Microsoft External Staff Moderator

2025-08-11T14:36:21.83+00:00
Hi Debajyoti Sarma,

Thanks for sharing the error details. What’s happening is that answerCall() returns before the call is fully registered in Azure’s backend. If play() is called immediately, the system may still be setting up the connection, leading to the "Call not found" error.

Instead of adding a fixed sleep, the recommended approach is to make it event-driven:

Pass a callbackUri when answering the call.

Wait for the CallConnected event from ACS to confirm the call is fully established.

Once you get that event, call play() with your audio file and loop=true.

This ensures the hold music starts as soon as ACS is ready, without hard-coded delays.

Answer Call API – with callbackUri option
Handle Call Automation events with the Event Processor

1 answer

Your answer

Bhargavi Naragani 7,445 Reputation points Microsoft External Staff Moderator

2025-08-11T10:29:28.63+00:00

Hi Debajyoti Sarma,

The ACS Call Automation model is event-driven and eventually consistent. Even though answerCall returns a connection ID, the underlying system needs time to register and make that connection visible for subsequent actions like media playback. So right after answering, getCallConnection(...) may not yet locate the active call.

Recent ACS updates introduced a playStarted event. This lets you start hold music and then know precisely when the play action has been recognized by the backend. You can:

Immediately after answering, call play(...) with loop=true to start hold music.

Then listen for the playStarted event to confirm that hold music is actually playing rather than guessing via timing.

This avoids the need to poll or sleep. The API now supports looping hold music, barge-in, and includes events to show when playback begins https://learn.microsoft.com/en-us/azure/communication-services/concepts/call-automation/play-action

Skip the extra getCallConnection(...) call, you already have the callConnection object from the answerCall() call. Use it directly to perform the play() operation, assuming the SDK instance is still valid. That avoids re-querying ACS's backend state.

ACS now also supports explicitly holding participants, which inherently plays hold music if configured https://learn.microsoft.com/en-us/azure/communication-services/whats-new

Hope this helps, if you have any further concerns or queries, please feel free to reach out to us.
Debajyoti Sarma 0 Reputation points

2025-08-11T12:44:40.2133333+00:00

Hi,

Immediately after answering, if I call play(...) with loop=true to start hold music I get following error and hold music doesn't get played. This I tried without extra getCallConnection(...)

RestError: Call not found. at handleErrorResponse (/Users/deba.jyoti/code/voice-orchestrator-be/node_modules/@azure/core-client/dist/commonjs/deserializationPolicy.js:148:19) at deserializeResponseBody (/Users/deba.jyoti/code/voice-orchestrator-be/node_modules/@azure/core-client/dist/commonjs/deserializationPolicy.js:83:45) at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

But If I add sleep before play it works fine.
Bhargavi Naragani 7,445 Reputation points Microsoft External Staff Moderator

2025-08-11T14:36:21.83+00:00

Hi Debajyoti Sarma,

Thanks for sharing the error details. What’s happening is that answerCall() returns before the call is fully registered in Azure’s backend. If play() is called immediately, the system may still be setting up the connection, leading to the "Call not found" error.

Instead of adding a fixed sleep, the recommended approach is to make it event-driven:

Pass a callbackUri when answering the call.

Wait for the CallConnected event from ACS to confirm the call is fully established.

Once you get that event, call play() with your audio file and loop=true.

This ensures the hold music starts as soon as ACS is ready, without hard-coded delays.

Answer Call API – with callbackUri option
Handle Call Automation events with the Event Processor

Answer 1

Debajyoti Sarma 0

Hi,

We will not be able to move to CallConnected event because we utilize from and to field of IncomingCall event to queue the call in job router queue after playing hold music. These fields are not available in CallConnected event. If we play hold music in CallConnected and queue the call in IncomingCall event, then both of these happens independently causing inconsistent state intermittently - hold music get played after call is attended by an agent. Overcoming this will need lot more complicate implementation.

We have tried this approach earlier and observed that time between first ring and hold music doesn't reduce more that 2-3 seconds. Right now it's around 15s which get reduced to 12s.

Is there a way to pass hold music while answering the call itself?

Bhargavi Naragani 7,445 Reputation points Microsoft External Staff Moderator

2025-08-12T11:45:00.0133333+00:00
Hi Debajyoti Sarma,

Unfortunately, there's no public API that lets you embed the hold audio in the answerCall call itself. However, there’s a better and more reliable pattern you can use:

Use the Hold API with playSourceInfo

Answer the call immediately, processing the IncomingCall event as you currently do, this ensures you have access to the from and to fields for your job router.

Immediately invoke the hold() API on the call connection. This API allows you to place the call participant on hold and simultaneously play hold music via the playSourceInfo parameter.

This pattern tightly couples your queue logic with the hold audio action, avoiding delays and preserving event data integrity.

It goes like this:

const options = { targetParticipant: { /* your callee info */ }, playSourceInfo: { kind: "file", file: { uri: audioFileUrl } } }; await callConnection.getCallMedia().hold(options);

https://learn.microsoft.com/en-us/rest/api/communication/callautomation/call-media/hold?view=rest-communication-callautomation-2025-06-15&tabs=HTTP
https://learn.microsoft.com/en-us/azure/communication-services/concepts/call-automation/play-action

Share via

answer call and play hold music

1 answer

Your answer