Raw New Markdown
Generating updated version of doc...
Rendered New Markdown
Generating updated version of doc...
---
title: Quickstart - Outbound calling using Call Automation
titleSuffix: An Azure Communication Services quickstart
description: In this quickstart, you learn how to make an outbound PSTN call using Azure Communication Services using Call Automation
author: jutik0
ms.author: jutik0
ms.date: 06/19/2023
ms.topic: quickstart
ms.service: azure-communication-services
ms.subservice: call-automation
ms.custom:
- mode-other
- sfi-ropc-nochange
---
## Prerequisites
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
- A deployed Communication Services resource. [Create a Communication Services resource](../../create-communication-resource.md).
- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls. If you have a free subscription, you can [get a trial phone number](../../telephony/get-trial-phone-number.md).
- Create and host an Azure Dev Tunnel. Instructions [here](/azure/developer/dev-tunnels/get-started).
- - Create and connect [Multi-service Foundry Tools to your Azure Communication Services resource](../../../concepts/call-automation/azure-communication-services-azure-cognitive-services-integration.md).
- Create a [custom subdomain](/azure/ai-services/cognitive-services-custom-subdomains) for your Azure AI services resource.
- [Node.js](https://nodejs.org/en/) LTS installation.
- [Visual Studio Code](https://code.visualstudio.com/download) installed.
- (Optional) A Microsoft Teams user with a phone license that is `voice` enabled. Teams phone license is required to add Teams users to the call. Learn more about Teams licenses [here](https://www.microsoft.com/microsoft-teams/compare-microsoft-teams-bundle-options). For more information to enable `voice` on your phone system, see [setting up your phone system](/microsoftteams/setting-up-your-phone-system).
## Sample code
Download or clone quickstart sample code from [GitHub](https://github.com/Azure-Samples/communication-services-javascript-quickstarts/tree/main/CallAutomation_OutboundCalling).
Navigate to `CallAutomation_OutboundCalling` folder and open the solution in a code editor.
## Set up the environment
Download the sample code and navigate to the project directory and run the `npm` command that installs the necessary dependencies and set up your developer environment.
```bash
npm install
```
## Set up and host your Azure DevTunnel
[Azure DevTunnels](/azure/developer/dev-tunnels/overview) is an Azure service that enables you to share local web services hosted on the internet. Use the DevTunnel CLI commands to connect your local development environment to the public internet. We use this endpoint to notify your application of calling events from the Azure Communication Services Call Automation service.
```bash
devtunnel create --allow-anonymous
devtunnel port create -p 8080
devtunnel host
```
## Update your application configuration
Then update your `.env` file with following values:
- `CONNECTION_STRING`: The connection string for your Azure Communication Services resource. You can find your Azure Communication Services connection string using the instructions [here](../../create-communication-resource.md).
- `CALLBACK_URI`: Once you have your DevTunnel host initialized, update this field with that URI.
- `TARGET_PHONE_NUMBER`: update field with the phone number you would like your application to call. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
- `ACS_RESOURCE_PHONE_NUMBER`: update this field with the Azure Communication Services phone number you have acquired. This phone number should use the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
- `COGNITIVE_SERVICES_ENDPOINT`: update field with your Azure AI Services endpoint.
- `TARGET_TEAMS_USER_ID`: (Optional) update field with the Microsoft Teams user Id you would like to add to the call. See [Use Graph API to get Teams user Id](../../../how-tos/call-automation/teams-interop-call-automation.md#step-2-use-the-graph-api-to-get-microsoft-entra-object-id-for-teams-users-and-optionally-check-their-presence).
```dosini
CONNECTION_STRING="<YOUR_CONNECTION_STRING>"
ACS_RESOURCE_PHONE_NUMBER ="<YOUR_ACS_NUMBER>"
TARGET_PHONE_NUMBER="<+1XXXXXXXXXX>"
CALLBACK_URI="<VS_TUNNEL_URL>"
COGNITIVE_SERVICES_ENDPOINT="<COGNITIVE_SERVICES_ENDPOINT>"
TARGET_TEAMS_USER_ID="<TARGET_TEAMS_USER_ID>"
```
## Make an outbound call and play media
To make the outbound call from Azure Communication Services, you use the phone number you provided to the environment. Ensure that the phone number is in the [E164](https://en.wikipedia.org/wiki/E.164) phone number format (e.g +18881234567)
The code makes an outbound call using the target_phone_number you've provided and place an outbound call to that number:
```typescript
const callInvite: CallInvite = {
targetParticipant: callee,
sourceCallIdNumber: {
phoneNumber: process.env.ACS_RESOURCE_PHONE_NUMBER || "",
},
};
const options: CreateCallOptions = {
cognitiveServicesEndpoint: process.env.COGNITIVE_SERVICES_ENDPOINT
};
console.log("Placing outbound call...");
acsClient.createCall(callInvite, process.env.CALLBACK_URI + "/api/callbacks", options);
```
## (Optional) Add a Microsoft Teams user to the call
You can add a Microsoft Teams user to the call using the `addParticipant` method with the `microsoftTeamsUserId` property. You first need to complete the prerequisite step [Authorization for your Azure Communication Services Resource to enable calling to Microsoft Teams users](../../../how-tos/call-automation/teams-interop-call-automation.md#step-1-authorization-for-your-azure-communication-services-resource-to-enable-calling-to-microsoft-teams-users). Optionally, you can also pass in a `sourceDisplayName` to control the text displayed in the toast notification for the Teams user.
```typescript
await acsClient.getCallConnection(callConnectionId).addParticipant({
targetParticipant: { microsoftTeamsUserId: process.env.TARGET_TEAMS_USER_ID },
sourceDisplayName: "Jack (Contoso Tech Support)"
});
```
## Start recording a call
The Call Automation service also enables the capability to start recording and store recordings of voice and video calls. You can learn more about the various capabilities in the Call Recording APIs [here](../../voice-video-calling/get-started-call-recording.md).
```typescript
const callLocator: CallLocator = {
id: serverCallId,
kind: "serverCallLocator",
};
const recordingOptions: StartRecordingOptions = {
callLocator: callLocator,
};
const response = await acsClient.getCallRecording().start(recordingOptions);
recordingId = response.recordingId;
```
## Respond to calling events
Earlier in our application, we registered the `CALLBACK_URI` to the Call Automation Service. The URI indicates the endpoint the service uses to notify us of calling events that happen. We can then iterate through the events and detect specific events our application wants to understand. We respond to the `CallConnected` event to get notified and initiate downstream operations. Using the `TextSource`, you can provide the service with the text you want synthesized and used for your welcome message. The Azure Communication Services Call Automation service plays this message upon the `CallConnected` event.
Next, we pass the text into the `CallMediaRecognizeChoiceOptions` and then call `StartRecognizingAsync`. This allows your application to recognize the option the caller chooses.
```typescript
callConnectionId = eventData.callConnectionId;
serverCallId = eventData.serverCallId;
console.log("Call back event received, callConnectionId=%s, serverCallId=%s, eventType=%s", callConnectionId, serverCallId, event.type);
callConnection = acsClient.getCallConnection(callConnectionId);
const callMedia = callConnection.getCallMedia();
if (event.type === "Microsoft.Communication.CallConnected") {
console.log("Received CallConnected event");
await startRecording();
await startRecognizing(callMedia, mainMenu, "");
}
async function startRecognizing(callMedia: CallMedia, textToPlay: string, context: string) {
const playSource: TextSource = {
text: textToPlay,
voiceName: "en-US-NancyNeural",
kind: "textSource"
};
const recognizeOptions: CallMediaRecognizeChoiceOptions = {
choices: await getChoices(),
interruptPrompt: false,
initialSilenceTimeoutInSeconds: 10,
playPrompt: playSource,
operationContext: context,
kind: "callMediaRecognizeChoiceOptions"
};
await callMedia.startRecognizing(callee, recognizeOptions)
}
```
## Handle Choice Events
Azure Communication Services Call Automation triggers the `api/callbacks` to the webhook we have setup and will notify us with the `RecognizeCompleted` event. The event gives us the ability to respond to input received and trigger an action. The application then plays a message to the caller based on the specific input received.
```typescript
else if (event.type === "Microsoft.Communication.RecognizeCompleted") {
if(eventData.recognitionType === "choices"){
console.log("Recognition completed, event=%s, resultInformation=%s",eventData, eventData.resultInformation);
var context = eventData.operationContext;
const labelDetected = eventData.choiceResult.label;
const phraseDetected = eventData.choiceResult.recognizedPhrase;
console.log("Recognition completed, labelDetected=%s, phraseDetected=%s, context=%s", labelDetected, phraseDetected, eventData.operationContext);
const textToPlay = labelDetected === confirmLabel ? confirmText : cancelText;
await handlePlay(callMedia, textToPlay);
}
}
async function handlePlay(callConnectionMedia:CallMedia, textContent:string){
const play : TextSource = { text:textContent , voiceName: "en-US-NancyNeural", kind: "textSource"}
await callConnectionMedia.playToAll([play]);
}
```
## Hang up the call
Finally, when we detect a condition that makes sense for us to terminate the call, we can use the `hangUp()` method to hang up the call.
```typescript
await acsClient.getCallRecording().stop(recordingId);
callConnection.hangUp(true);
```
## Run the code
To run the application, open a Terminal window and run the following command:
```bash
npm run dev
```
View on GitHub