Quickstart: Outbound call to a telephone number
Get started with Azure Communication Services by using the Communication Services Calling SDK to add PSTN calling to your app.
Important
Azure Communication Services supports emergency calling to emergency numbers in the United States, Puerto Rico, Canada, Denmark, and the United Kingdom only.
Azure Communication Services voice calling (PSTN) can be used to dial emergency number 911 in the United States, Puerto Rico, and Canada, to dial emergency number 112 in Denmark, and to dial emergency numbers 999 and 112 in the United Kingdom. Azure Communication Services doesn't currently support dialing those emergency numbers from outside those countries or regions, or dialing emergency services in other countries or regions.
Sample Code
Find the finalized code for this quickstart on GitHub
Note
Outbound calling to a telephone number can be accessed using the Azure Communication Services UI Library. The UI Library enables developers to add a call client that is PSTN enabled into their application with only a couple lines of code.
Prerequisites
- An Azure account with an active subscription. Create an account for free.
- A deployed Communication Services resource. Create a Communication Services resource.
- A phone number acquired in your Communication Services resource, or Azure Communication Services Direct routing configured. If you have a free subscription, you can get a trial phone number.
- A
User Access Token
to enable the call client. For more information on how to get aUser Access Token
Setting up
Create a new Node.js application
Open your terminal or command window create a new directory for your app, and navigate to it.
mkdir calling-quickstart
cd calling-quickstart
Run npm init -y
to create a package.json file with default settings.
npm init -y
Install the package
Use the npm install
command to install the Azure Communication Services Calling SDK for JavaScript.
npm install @azure/communication-common --save
npm install @azure/communication-calling --save
The --save
option lists the library as a dependency in your package.json file.
Set up the app framework
This quickstart uses parcel to bundle the application assets. Run the following command to install it and list it as a development dependency in your package.json:
npm install parcel --save-dev
Create an index.html file in the root directory of your project. We'll use this file to configure a basic layout that will allow the user to place a call.
Here's the code:
<!DOCTYPE html>
<html>
<head>
<title>Communication Client - Calling Sample</title>
</head>
<body>
<h4>Azure Communication Services</h4>
<h1>Calling Quickstart</h1>
<input
id="callee-phone-input"
type="text"
placeholder="Who would you like to call?"
style="margin-bottom:1em; width: 230px;"
/>
<div>
<button id="call-phone-button" type="button">
Start Call
</button>
<button id="hang-up-phone-button" type="button" disabled="true">
Hang Up
</button>
</div>
<script src="./app.js" type="module"></script>
</body>
</html>
Create a file in the root directory of your project called app.js to contain the application logic for this quickstart. Add the following code to import the calling client and get references to the DOM elements so we can attach our business logic.
import { CallClient, CallAgent } from "@azure/communication-calling";
import { AzureCommunicationTokenCredential } from '@azure/communication-common';
let call;
let callAgent;
const calleePhoneInput = document.getElementById("callee-phone-input");
const callPhoneButton = document.getElementById("call-phone-button");
const hangUpPhoneButton = document.getElementById("hang-up-phone-button");
async function init() {
const callClient = new CallClient();
const tokenCredential = new AzureCommunicationTokenCredential('<USER ACCESS TOKEN with VoIP scope>');
callAgent = await callClient.createCallAgent(tokenCredential);
//callPhoneButton.disabled = false;
}
init();
Start a call to phone
Specify phone number you acquired in Communication Services resource that is used to start the call:
Warning
Phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)
Add an event handler to initiate a call to the phone number you provided when the callPhoneButton
is clicked:
callPhoneButton.addEventListener("click", () => {
// start a call to phone
const phoneToCall = calleePhoneInput.value;
call = callAgent.startCall(
[{phoneNumber: phoneToCall}], { alternateCallerId: {phoneNumber: 'YOUR AZURE REGISTERED PHONE NUMBER HERE: +12223334444'}
});
// toggle button states
hangUpPhoneButton.disabled = false;
callPhoneButton.disabled = true;
});
End a call to phone
Add an event listener to end the current call when the hangUpPhoneButton
is clicked:
hangUpPhoneButton.addEventListener("click", () => {
// end the current call
call.hangUp({
forEveryone: true
});
// toggle button states
hangUpPhoneButton.disabled = true;
callPhoneButton.disabled = false;
});
The forEveryone
property ends the call for all call participants.
Run the code
Use the command npx parcel index.html
to build and run your app.
Open your browser and navigate to http://localhost:1234/
. You should see the following web application:
You can place a call to a real phone number by providing a phone number in the added text field and clicking the Start Phone Call button.
Important
Azure Communication Services supports emergency calling to emergency numbers in the United States, Puerto Rico, Canada, Denmark, and the United Kingdom only.
Azure Communication Services voice calling (PSTN) can be used to dial emergency number 911 in the United States, Puerto Rico, and Canada, to dial emergency number 112 in Denmark, and to dial emergency numbers 999 and 112 in the United Kingdom. Azure Communication Services doesn't currently support dialing those emergency numbers from outside those countries or regions, or dialing emergency services in other countries or regions.
Sample Code
Find the finalized code for this quickstart on GitHub
Prerequisites
- An Azure account with an active subscription. Create an account for free.
- A deployed Communication Services resource. Create a Communication Services resource.
- A phone number acquired in your Communication Services resource, or Azure Communication Services Direct Routing configured. If you have a free subscription, you can get a trial phone number.
- A
User Access Token
to enable the call client. For more information on how to get aUser Access Token
- Complete the quickstart for getting started with adding calling to your application
Prerequisite check
- To view the phone numbers associated with your Communication Services resource, sign in to the Azure portal, locate your Communication Services resource and open the phone numbers tab from the left navigation pane.
Setting up
Add PSTN functionality to your app
Add the PhoneNumber
type to your app by modifying MainActivity.java:
import com.azure.android.communication.common.PhoneNumberIdentifier;
Start a call to phone
Specify the phone number you acquired from within your Communication Services resource. This number is used as a caller ID to start the call:
Warning
Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)
Modify startCall()
event handler in MainActivity.java, so that it handles phone calls:
private void startCall() {
EditText calleePhoneView = findViewById(R.id.callee_id);
String calleePhone = calleePhoneView.getText().toString();
PhoneNumberIdentifier callerPhone = new PhoneNumberIdentifier("+12223334444");
StartCallOptions options = new StartCallOptions();
options.setAlternateCallerId(callerPhone);
options.setVideoOptions(new VideoOptions(null));
call = agent.startCall(
getApplicationContext(),
new PhoneNumberIdentifier[] {new PhoneNumberIdentifier(calleePhone)},
options);
}
Launch the app and call the echo bot
The app can now be launched using the "Run App" button on the toolbar (Shift+F10). To make a call, provide a phone number in the added text field and select the CALL button.
Warning
Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)
Important
Azure Communication Services supports emergency calling to emergency numbers in the United States, Puerto Rico, Canada, Denmark, and the United Kingdom only.
Azure Communication Services voice calling (PSTN) can be used to dial emergency number 911 in the United States, Puerto Rico, and Canada, to dial emergency number 112 in Denmark, and to dial emergency numbers 999 and 112 in the United Kingdom. Azure Communication Services doesn't currently support dialing those emergency numbers from outside those countries or regions, or dialing emergency services in other countries or regions.
Prerequisites
- An Azure account with an active subscription. Create an account for free.
- A deployed Communication Services resource. Create a Communication Services resource.
- A phone number acquired in your Communication Services resource, or Azure Communication Services Direct routing configured. If you have a free subscription, you can get a trial phone number.
- A
User Access Token
to enable the call client. For more information on how to get aUser Access Token
- Complete the quickstart for getting started with adding calling to your application
Prerequisite check
- To view the phone numbers associated with your Communication Services resource, sign in to the Azure portal, locate your Communication Services resource and open the phone numbers tab from the left navigation pane.
- You can build and run your app with Azure Communication Services Calling SDK for iOS:
Setting up
Start a call to phone
Specify phone number you acquired in Communication Services resource that is used to start the call:
Warning
Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)
Modify startCall
event handler that is performed when the Start Call button is tapped:
func startCall() {
// Ask permissions
AVAudioSession.sharedInstance().requestRecordPermission { (granted) in
if granted {
let startCallOptions = StartCallOptions()
startCallOptions.alternateCallerId = PhoneNumberIdentifier(phoneNumber: "<YOUR AZURE REGISTERED PHONE NUMBER>")
self.callAgent!.startCall(participants: [PhoneNumberIdentifier(phoneNumber: self.callee)], options: startCallOptions) { (call, error) in
if (error == nil) {
self.call = call
} else {
print("Failed to get call object")
}
}
}
}
}
Run the code
You can build and run your app on iOS simulator by selecting Product > Run or by using the (⌘-R) keyboard shortcut.
You can make a call to phone by providing a phone number in the added text field and clicking the Start Call button.
Warning
Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)
Note
The first time you make a call, the system will prompt you for access to the microphone. In a production application, you should use the AVAudioSession
API check the permission status and gracefully update your application's behavior when permission is not granted.
Clean up resources
If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about cleaning up resources.
Next steps
For more information, see the following articles:
- Learn about Calling SDK capabilities
- Learn more about how calling works
- Learn about Number lookup capabilities