Making Phone Calls from Blazor WebAssembly with Twilio Voice

<script src="https://sdk.twilio.com/js/client/v1.13/twilio.js"></script>

You can learn more about the Twilio Client JS SDK in Twilio’s documentation.

Managing Twilio calls with JavaScript #

Now that the Twilio Client JS SDK has been installed in the Blazor Client you can start using the library to manage calls.

Inside TwilioBlazorPhonecalls.Client\wwwroot\js\dialer.js, you’ll need to add JavaScript functions that are accessible from .NET.

Declare a global variable called dialer or explicitly declare the dialer variable as a property on the window object, which achieves the same result. Initialize the dialer variable with an object holding the following properties and functions.

Add the following JavaScript code to TwilioBlazorPhonecalls.Client\wwwroot\js\dialer.js:

window.dialer = {
    device: new Twilio.Device(),
    setupTwilioDevice: function (jwtToken) {
        var options = {
            closeProtection: true // will warn user if you try to close browser window during an active call
        };
        this.device.setup(jwtToken, options);
    },
    setupTwilioEvents: function () {
        // inside of Twilio events scope the 'this' context is redefined and will not point to 'window.dialer'
        // the variable 'self' is introduced to conveniently access the 'this' context from the outer scope inside of the events scope
        var self = this;
        this.device.on('ready', function () {
            // notify Blazor Component
        });

        this.device.on('error', function (error) {
            console.error(error);
            // notify Blazor Component
        });

        this.device.on('connect', function (connection) {
            if (connection.direction === "OUTGOING") {
                // notify Blazor Component
            } else {
                // notify Blazor Component
            }
        });

        this.device.on('disconnect', function () {
            // notify Blazor Component
        });

        this.device.on('incoming', function (connection) {
            // notify Blazor Component
        });

        this.device.on('cancel', function () {
            // notify Blazor Component
        });
    },
    startCall: function (phoneNumber) {
        // To parameter is a defined property by Twilio, but you could just as well use any other property name
        // and it will be passed to your TwiML webhook as meta data
        this.device.connect({ "To": phoneNumber });
    },
    endCall: function () {
        var connection = this.device.activeConnection();
        if (connection) {
            connection.disconnect();
        }
    },
    acceptCall: function () {
        var connection = this.device.activeConnection();
        if (connection) {
            connection.accept();
        }
    },
    rejectCall: function () {
        var connection = this.device.activeConnection();
        if (connection) {
            connection.reject();
        }
    },
    destroy: function () {
        this.device.destroy();
    }
};

Here’s an overview of the properties and functions inside of the dialer object:

device: Twilio.Device is a virtual phone, if you will. This class holds the functions to connect to Twilio, accept calls, deny calls, etc. On page load, an instance of Twilio.Device will be created and stored in window.dialer.device.

setupTwilioDevice: This function accepts a jwtToken argument, a JSON Web Token that is the authentication token necessary to connect to Twilio. This token also includes the necessary information for Twilio to identify your TwiML application holding your voice webhook URL. The jwtToken will be passed in from Blazor .NET after having been  generated by your server project.

This function will call the setup function on the Twilio.Device instance, which will perform the authentication against Twilio.

setupTwilioEvents: This function configures all relevant events for the dialer component:

• ready: triggers when the Twilio.Device is ready to make and receive phone calls after successfully authenticating with Twilio
• error: triggers when any error occurs
• connect: triggers when an incoming or outgoing connection is established
• disconnect: triggers when the connection is closed
• incoming: triggers when there’s an incoming connection
• cancel: triggers when a connection was closed before it was accepted

When these events occur, the relevant information should be passed to the Blazor Dialer component in .NET so it can update its state appropriately. You’ll replace the stubs with functional code in a forthcoming step.

startCall: use this function to initiate a phone call to the specified phonenumber. This function accepts a phonenumber which will be passed to the connect function on the Twilio.Device instance. The phonenumber is passed as metadata to the voice webhook configured in your TwiML application.

This function is step 1 of the Figure 1: Workflow diagram for outgoing phone calls and initiates the entire workflow.

endCall: When there’s an active phone call, you can use this function to end the call.
It retrieves the active connection using the activeConnection function on the Twilio.Device instance. If the activeConnection function returns a connection, the disconnect function will be called on the connection which will close the connection.

acceptCall: When there’s an incoming phone call, you can use this function to accept the call. It retrieves the active connection using the activeConnection function on the Twilio.Device instance. If the activeConnection function returns a connection, the accept function will be called on the connection which will start the phone call.

rejectCall: When there’s an incoming phone call, you can use this function to reject the call. It retrieves the active connection using the activeConnection function on the Twilio.Device instance. If the activeConnection function returns a connection, the reject function will be called on the connection which will reject the phone call.

destroy: This function calls the destroy function on the Twilio.Device instance. It cleans up all event listeners, connections, etc. You should call this function to clean up any resources when removing the Dialer component from the Blazor application.

Integrating JavaScript with the Blazor Dialer component #

Blazor introduced a way to call JavaScript functions from .NET, and .NET methods from JavaScript, a process referred to as JavaScript Interop.

Call JavaScript functions from the Blazor Dialer component #

To invoke JavaScript functions from Blazor you need an instance of the IJSRuntime interface.

You can obtain an instance using ASP.NET Core Blazor dependency injection. If you want to have the IJSRuntime injected into a .razor component, use the @inject directive at the top of your component, like this:

@inject IJSRuntime js

There are two instance methods used to call JavaScript functions from .NET using the IJSRuntime class:

InvokeAsync: This method will invoke the specified JavaScript function. It has one required parameter: a string to specify which JavaScript function to run. After the required parameter, you can pass as many extra parameters as you need to. Those subsequent parameters will be passed along to the JavaScript function.

You also must specify the return type you are expecting to receive from the JavaScript function using the generic type parameter. Blazor will try to convert the JavaScript return value to the requested .NET type.

InvokeVoidAsync: As the name gives away, this method functions like InvokeAsync, but it doesn't return the JavaScript return value.

Note: Even though the JavaScript return value isn't returned to you, it is still converted to a .NET type and then discarded. This behavior will change in future versions so that the JavaScript return value isn't unnecessarily converted.

For more details on JavaScript interop, read Communicating between .NET and JavaScript in Blazor with in-browser samples.

Update TwilioBlazorPhonecalls.Client\Components\Dialer.razor so an instance of IJSRuntime is injected by adding the following line below @inject ILogger<Dialer> logger:

@inject IJSRuntime js

Wire up the .NET methods in Dialer.razor so they call the relevant JavaScript functions using InvokeVoidAsync by replacing the existing methods with // TO IMPLEMENT comments using the following C# code:

private async Task StartCall()
{
    await js.InvokeVoidAsync("dialer.startCall", dialNumber);
}

private async Task EndCall()
{
    await js.InvokeVoidAsync("dialer.endCall");
}

private async Task AcceptCall()
{
    await js.InvokeVoidAsync("dialer.acceptCall");
}

private async Task RejectCall()
{
    hasIncomingConnection = false;
    message = "";
    await js.InvokeVoidAsync("dialer.rejectCall");
}

protected override async Task OnInitializedAsync()
{
    await js.InvokeVoidAsync("dialer.setupTwilioEvents");
    var jwtToken = await GetTwilioAuthenticationTokenAsync();
    await js.InvokeVoidAsync("dialer.setupTwilioDevice", jwtToken);
}

private async Task<string> GetTwilioAuthenticationTokenAsync()
{
    // TODO: jwtToken will need to be retrieved from the backend using HttpClient
    // use a dummy value for now 
    return "TEMP TOKEN (WILL NOT WORK)";
}

// IAsyncDisposable isn't supported in Blazor .NET Core 3.1, but will be in future versions
// for now use IDisposable and fire and forget a task to call dialer.destroy
public void Dispose()
{
    js.InvokeVoidAsync("dialer.destroy");
}

The new code does the following:

StartCall: Invoked when clicking the “Call” button. Invokes the dialer.startCall JavaScript function and passes dialNumber (bound to input) as a parameter.

EndCall: Invoked when clicking the “Hang up” button. Invokes the dialer.endCall JavaScript function.

AcceptCall: Invoked when clicking the “Accept” button. The “Accept” button is only visible when the boolean field hasIncomingConnection is set to true. Invokes the  dialer.acceptCall JavaScript function.

RejectCall: Invoked when clicking the “Reject” button. The “Reject” button is only visible when the boolean field hasIncomingConnection is set to true. Invokes the dialer.rejectCall JavaScript function.

Dispose: Not all Blazor components need to implement the IDisposible interface, but if you have some resources to clean up you should implement it. In this case, the dialer.destroy JavaScript function is invoked inside the Dispose method. You can’t await the async InvokeVoidAsync, but you can still call it and it will “fire and forget”.

Note: In .NET 5.0, Blazor supports IAsyncDisposable, so you can await the async method. You can see the implementation here in the companion repository.

Fetch the Twilio authentication token #

Instead of returning a dummy string as an authentication token, you need to fetch the authentication token from the TokenController from the server.

Add a static HttpClient at the top of the code section of Dialer.razor and update the GetTwilioAuthenticationTokenAsync method to send a GET request to https://localhost:5003/token by inserting the following statement after @code:

private static readonly HttpClient httpClient = new HttpClient();

Replace the body of the method so it looks like the following:

private async Task<string> GetTwilioAuthenticationTokenAsync()
{
    var jwtToken = await httpClient.GetStringAsync("https://localhost:5003/token");
    return jwtToken;
}

If you’ve been coding this solution in Visual Studio 2019, all your errors and warnings should be resolved at this point.

Call .NET methods from JavaScript #

In addition to calling JavaScript functions from .NET, you can also call .NET methods from JavaScript. You must decorate the .NET methods you want to expose to JavaScript using the JSInvokable attribute.

You can call .NET instance methods, but you need a reference to the object before you can invoke its methods. You can create a DotNetObjectReference instance by calling DotNetObjectReference.Create. You need to pass in the object you want a reference to as a parameter. When a DotNetObjectReference is returned to JavaScript from a .NET method or passed to a JavaScript function, it is converted to a JavaScript object which you can use to call the methods on the .NET object.

The JavaScript object converted from a DotNetObjectReference instance has two functions to invoke .NET methods:

invokeMethod: Invokes the specified .NET method and returns the .NET value converted as a JavaScript value. The first parameter is the identifier/method name of the .NET method. Any subsequent parameters will be converted to .NET values and passed to the .NET method.

invokeMethodAsync: Invokes the specified .NET method and returns a JavaScript Promise. When the Promise is fulfilled, the Promise result will be the return value from the .NET method. The first parameter is the identifier/method name of the .NET method. Any subsequent parameters will be converted to .NET values and passed to the .NET method.

For more details on JavaScript interop, read:

• Communicating between .NET and JavaScript in Blazor with in-browser samples

The Blazor Dialer component needs to create a DotNetObjectReference pointing to itself and then pass it to a JavaScript function to store it.

In the TwilioBlazorPhonecalls.Client/Components/Dialer.razor file, add the following field declaration to the existing private member variables:

protected override async Task OnInitializedAsync()
{
    dotNetObjectReference = DotNetObjectReference.Create(this);
    await js.InvokeVoidAsync("dialer.setDotNetObjectReference", dotNetObjectReference);
    await js.InvokeVoidAsync("dialer.setupTwilioEvents");
    var jwtToken = await GetTwilioAuthenticationTokenAsync();
    await js.InvokeVoidAsync("dialer.setupTwilioDevice", jwtToken);
}

The Dispose method should dispose of the object reference, so add a statement so the contents look like the following:

public void Dispose()
{
    js.InvokeVoidAsync("dialer.destroy");
    dotNetObjectReference?.Dispose();
}

The Dialer component invokes the JavaScript function dialer.setDotNetObjectReference, which still needs to be created.

Update the TwilioBlazorPhonecalls.Client\wwwroot\js\dialer.js file so the beginning of window.dialer object looks like the following:

window.dialer = {
    device: new Twilio.Device(),
    dotNetObjectReference: null,
    setDotNetObjectReference: function (dotNetObjectReference) {
        this.dotNetObjectReference = dotNetObjectReference;
    },
    setupTwilioDevice: function (jwtToken) {
        var options = {
            closeProtection: true // will warn user if you try to close browser window during an active call
        };
        this.device.setup(jwtToken, options);
    },
...

Once the dotNetObjectReference property is set you can call .NET methods on the Blazor Dialer component. Update the dialer.setupTwilioEvents function so every event calls back into the Dialer component.

Replace the existing setupTwilioEvents function with the follow code:

setupTwilioEvents: function () {
    // Inside of Twilio events scope the 'this' context is redefined and will not point to 'window.dialer'
    // The variable 'self' is introduced to conveniently access the 'this' context from the outer scope inside of the events scope
    var self = this;
    this.device.on('ready', function () {
        self.dotNetObjectReference.invokeMethod('OnTwilioDeviceReady');
    });

    this.device.on('error', function (error) {
        console.error(error);
        self.dotNetObjectReference.invokeMethod('OnTwilioDeviceError', error.message);
    });

    this.device.on('connect', function (connection) {
        if (connection.direction === "OUTGOING") {
            self.dotNetObjectReference.invokeMethod('OnTwilioDeviceConnected', connection.message['To']);
        } else {
            self.dotNetObjectReference.invokeMethod('OnTwilioDeviceConnected', connection.parameters['From']);
        }
    });

    this.device.on('disconnect', function () {
        self.dotNetObjectReference.invokeMethod('OnTwilioDeviceDisconnected');
    });

    this.device.on('incoming', function (connection) {
        self.dotNetObjectReference.invokeMethod('OnTwilioDeviceIncomingConnection', connection.parameters['From']);
    });

    this.device.on('cancel', function () {
        self.dotNetObjectReference.invokeMethod('OnTwilioDeviceCanceled');
    });
}

These .NET methods do not yet exist. Create the following .NET methods in TwilioBlazorPhonecalls.Client\Components\Dialer.razor by inserting the following C# code in the @code section between the fields and the existing methods:

[JSInvokable]
public void OnTwilioDeviceReady()
{
    isTwilioDeviceReady = true;
    StateHasChanged();
}

[JSInvokable]
public void OnTwilioDeviceError(string error)
{
    message = error;
    logger.LogError(error);
    StateHasChanged();
}

[JSInvokable]
public void OnTwilioDeviceConnected(string phoneNumber)
{
    isTwilioDeviceConnected = true;
    hasIncomingConnection = false;
    message = $"Calling {phoneNumber}";
    StateHasChanged();
}

[JSInvokable]
public void OnTwilioDeviceDisconnected()
{
    isTwilioDeviceConnected = false;
    hasIncomingConnection = false;
    message = "";
    StateHasChanged();
}

[JSInvokable]
public void OnTwilioDeviceIncomingConnection(string phoneNumber)
{
    hasIncomingConnection = true;
    message = $"{phoneNumber} is calling you";
    StateHasChanged();
}

[JSInvokable]
public void OnTwilioDeviceCanceled()
{
    hasIncomingConnection = false;
    message = "";
    StateHasChanged();
}

Each of these methods which respond to events in the Twilio.Device will modify the local state and call the StateHasChanged method to trigger a re-render of the component.

Test the code #

At this point you have a partially functional Twilio Voice client. To test this, run the client:

dotnet run -p TwilioBlazorPhonecalls.Client

Open a second shell and run the server:

dotnet run -p TwilioBlazorPhonecalls.Server

Open your browser and navigate to https://localhost:5001/. You can find the Dialer component at the bottom right.

At this point the virtual Twilio device is configured and the authentication was successful, but when you try to initiate a call you hear the following voice message:

“We are sorry, an application error has occurred.”

This is because no voice webhook URL is configured to route the connection. Your next step is to implement the webhooks.

Implementing voice webhooks #

The client is completed, but calls are not going out or coming in due to the lack of voice webhooks. In this section you will do the following:

• Add a controller to route phone calls
• Add a controller action to route outgoing phone calls
• Add a controller action to route incoming phone calls
• Use ngrok to make your local server publicly accessible
• Configure voice webhook URL on TwiML application for outgoing phone calls
• Configure voice webhook URL on Twilio phone number for incoming phone calls

Implement outgoing phone calls webhook #

Add the Twilio.AspNet.Core NuGet package to the TwilioBlazorPhonecalls.Server server project:

dotnet add TwilioBlazorPhonecalls.Server package Twilio.AspNet.Core

This library adds some convenient classes which help with implementing Twilio webhooks. Learn more at the Twilio.AspNet.Core GitHub repository.

Create a new controller at TwilioBlazorPhonecalls.Server\Controllers\VoiceController.cs:

using System;
using System.Linq;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
using Twilio.AspNet.Core;
using Twilio.TwiML;
using Twilio.TwiML.Voice;

namespace TwilioBlazorPhonecalls.Server.Controllers
{
    [ApiController]
    public class VoiceController : TwilioController
    {
        private readonly IConfiguration configuration;
        private readonly ILogger<VoiceController> logger;

        public VoiceController(IConfiguration configuration, ILogger<VoiceController> logger)
        {
            this.configuration = configuration;
            this.logger = logger;
        }

        [HttpPost]
        [Route("voice/outgoing")]
        public TwiMLResult Outgoing([FromForm] string to)
        {
            string twilioPhoneNumber = configuration["TwilioPhoneNumber"];
            var response = new VoiceResponse();
            var dial = new Dial();
            logger.LogInformation($"Calling {to}");
            dial.CallerId = twilioPhoneNumber;
            dial.Number(to);
            response.Append(dial);
            return TwiML(response);
        }
    }
}

Note how VoiceController inherits from the TwilioController class provided by the Twilio.AspNet.Core library. The TwilioController class provides the TwiML method which you can use to return VoiceResponse and MessagingResponse instances.

When the Blazor client connects to Twilio, Twilio will send an HTTP POST request to your webhook with many <form> parameters including the metadata passed along to Twilio.Device.connect JavaScript function. Your webhook creates a TwiML response that instructs Twilio to Dial the phone number in the to parameter from the phone number specified in the CallerId which is your Twilio phone number.

To quickly verify if this works and what it looks like, run the server again:

dotnet run -p TwilioBlazorPhonecalls.Server

Invoke-WebRequest https://localhost:5003/voice/outgoing -Method Post -Body @{"To" = "+1234567890"}

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Dial callerId="YOUR_TWILIO_PHONE_NUMBER">
        <Number>+1234567890</Number>
    </Dial>
</Response>

./ngrok http https://localhost:5003

dotnet run -p TwilioBlazorPhonecalls.Server

Invoke-WebRequest https://[YOUR_SUBDOMAIN].ngrok.io/voice/outgoing -Method Post -Body @{"To" = "+1234567890"}

twilio api:core:applications:update --sid=[YOUR_TWIML_APPLICATION_SID] --voice-url=https://[YOUR_SUBDOMAIN].ngrok.io/voice/outgoing --voice-method=POST

$ApplicationSid = "YOUR_TWIML_APPLICATION_SID"

# Make sure ngrok is running before running this
$NgrokApi = 'http://127.0.0.1:4040/api'
$TwilioTunnelsObject = (Invoke-WebRequest "$NgrokApi/tunnels").Content | ConvertFrom-Json
$PublicBaseUrl = $TwilioTunnelsObject.tunnels.public_url | Where-Object {$_.StartsWith('https')}

$PublicOutgoingVoiceUrl = "$PublicBaseUrl/voice/outgoing"
twilio api:core:applications:update --sid=$ApplicationSid --voice-url=$PublicOutgoingVoiceUrl --voice-method=POST

./UpdateTwilioWebhooks.ps1

[HttpPost]
[Route("voice/incoming")]
public TwiMLResult Incoming([FromForm] string from)
{
    logger.LogInformation($"Receiving call from {from}");
    var response = new VoiceResponse();
    var dial = new Dial();
    logger.LogInformation($"Calling blazor_client");
    dial.CallerId = from;
    // client has to match the identity specified in TokenController
    dial.Client("blazor_client"); 
    response.Append(dial);
    return TwiML(response);
}

dotnet run -p TwilioBlazorPhonecalls.Server

Invoke-WebRequest https://localhost:5003/voice/incoming -Method Post -Body @{"From" = "+1234567890"}

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Dial callerId="+1234567890">
        <Client>blazor_client</Client>
    </Dial>
</Response>

./ngrok http https://localhost:5003

twilio phone-numbers:update [YOUR_TWILIO_PHONE_NUMBER] --voice-url=https://[YOUR_SUBDOMAIN].ngrok.io/voice/incoming --voice-method=POST

$ApplicationSid = "YOUR_TWIML_APPLICATION_SID"
$TwilioPhonenumber = "YOUR_TWILIO_PHONE_NUMBER"

# Make sure ngrok is running before running this
$NgrokApi = 'http://127.0.0.1:4040/api'
$TwilioTunnelsObject = (Invoke-WebRequest "$NgrokApi/tunnels").Content | ConvertFrom-Json
$PublicBaseUrl = $TwilioTunnelsObject.tunnels.public_url | Where-Object {$_.StartsWith('https')}

$PublicOutgoingVoiceUrl = "$PublicBaseUrl/voice/outgoing"
twilio api:core:applications:update --sid=$ApplicationSid --voice-url=$PublicOutgoingVoiceUrl --voice-method=POST

$PublicIncomingVoiceUrl = "$PublicBaseUrl/voice/incoming"
twilio phone-numbers:update $TwilioPhonenumber --voice-url=$PublicIncomingVoiceUrl --voice-method=POST