Quickstart: Call To Phone

Get started with Azure Communication Services by using the Communication Services Calling SDK to add PSTN calling to your app.

Important

Azure Communication Services does not support emergency calling

Azure Communication Services' outbound voice calling services cannot be used for contacting emergency services. You should maintain traditional telephone service for placing emergency calls.

Sample Code

Find the finalized code for this quickstart on GitHub

Prerequisites

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@1.1.0 --save

The following versions of webpack are recommended for this quickstart:

"webpack": "^4.42.0",
"webpack-cli": "^3.3.11",
"webpack-dev-server": "^3.10.3"

The --save option lists the library as a dependency in your package.json file.

Set up the app framework

This quickstart uses webpack to bundle the application assets. Run the following command to install the webpack, webpack-cli and webpack-dev-server npm packages and list them as development dependencies in your package.json:

npm install webpack@4.42.0 webpack-cli@3.3.11 webpack-dev-server@3.10.3 --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>
      &nbsp;
      <button id="hang-up-phone-button" type="button" disabled="true">
        Hang Up
      </button>
    </div>
    <script src="./bundle.js"></script>
  </body>
</html>

Create a file in the root directory of your project called client.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 PSTN 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 will be used to start the call:

Warning

Note that 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 webpack-dev-server to build and run your app. Run the following command to bundle the application host on a local webserver:

npx webpack-dev-server --entry ./client.js --output bundle.js --debug --devtool inline-source-map

Open your browser and navigate to http://localhost:8080/. You should see the following:

Screenshot of the completed JavaScript 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.

Warning

Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)

Important

Azure Communication Services does not support emergency calling

Azure Communication Services' outbound voice calling services cannot be used for contacting emergency services. You should maintain traditional telephone service for placing emergency calls.

Sample Code

Find the finalized code for this quickstart on GitHub

Prerequisites

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 will be used to start the call:

Warning

Note that phone numbers shold 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). You can make an call to phone by providing a phone number in the added text field and clicking the CALL button.

Warning

Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)

Screenshot showing the completed application.

Important

Azure Communication Services does not support emergency calling

Azure Communication Services' outbound voice calling services cannot be used for contacting emergency services. You should maintain traditional telephone service for placing emergency calls.

Prerequisites

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 will be 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 will be 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.

Final look and feel of the quick start app

You can make an 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: