AlexaSkillsKit.NET

.NET library to write Alexa skills that's interface-compatible with Amazon's AlexaSkillsKit for Java and matches that functionality:

• handles the (de)serialization of Alexa requests & responses into easy-to-use object models
• verifies authenticity of the request by validating its signature and timestamp
• code-reviewed and vetted by Amazon (Alexa skills written using this library passed certification)
• 🆕 supports following interfaces:
  • AudioPlayer
  • PlaybackController
  • Display
  • Dialog
  • VideoApp

Beyond the functionality in Amazon's AlexaSkillsKit for Java, AlexaSkillsKit.NET:

• performs automatic session management so you can easily build conversational Alexa apps
• supports asynchronous programming model
• 🆕 can be extended to support custom and new coming interfaces and request types (see Implement external interface section), such as:
  • Skill Events

This library was originally developed for and is in use at https://freebusy.io

This library is available as a NuGet package at https://www.nuget.org/packages/AlexaSkillsKit.NET/

How To Use

1. Set up your development environment

Read Getting started with Alexa App development for Amazon Echo using .NET on Windows

Note, that if you are hosting your API in Amazon Lambda, Azure Function, Azure Web App or other well-known cloud service, you can use parent domain certificate instead of providing your own.

2. Implement your skill as a "Speechlet"

If your Alexa skill does any kind of asynchronous I/O, it's recommended that you derive your app from the SpeechletBase class and implement these methods as defined by ISpeechletAsyncV2:

public interface ISpeechletAsyncV2
{
    Task<SpeechletResponse> OnIntentAsync(IntentRequest intentRequest, Session session, Context context);
    Task<SpeechletResponse> OnLaunchAsync(LaunchRequest launchRequest, Session session);
    Task OnSessionStartedAsync(SessionStartedRequest sessionStartedRequest, Session session);
    Task OnSessionEndedAsync(SessionEndedRequest sessionEndedRequest, Session session);
}

Alternatively, you can implement synchronous ISpeechletV2 interface:

public interface ISpeechletV2
{
    SpeechletResponse OnIntent(IntentRequest intentRequest, Session session, Context context);
    SpeechletResponse OnLaunch(LaunchRequest launchRequest, Session session);
    void OnSessionStarted(SessionStartedRequest sessionStartedRequest, Session session);
    void OnSessionEnded(SessionEndedRequest sessionEndedRequest, Session session);
}

To handle external interface requests, your speechlet can implement additional interfaces either synchronous or asynchronous:

• IAudioPlayerSpeechletAsync or IAudioPlayerSpeechlet for "AudioPlayer." and "PlaybackController." requests.
• IDisplaySpeechletAsync or IDisplaySpeechlet for "Display.*" requests.

For backwards compatibility Speechlet and SpeechletAsync abstract classes are still available, along with deprecated ISpeechlet and ISpeechletAsync interfaces. Note, that old interfaces don't support Context object.

Take a look at https://github.com/AreYouFreeBusy/AlexaSkillsKit.NET/blob/master/AlexaSkillsKit.Sample/Speechlet/SampleSessionSpeechlet.cs for an example.

3. Wire-up "Speechlet" to HTTP hosting environment

The Sample app is using ASP.NET 4.5 WebApi 2 so wiring-up requests & responses from the HTTP hosting environment (i.e. ASP.NET 4.5) to the "Speechlet" is just a matter of writing a 2-line ApiController like this https://github.com/AreYouFreeBusy/AlexaSkillsKit.NET/blob/master/AlexaSkillsKit.Sample/Speechlet/AlexaController.cs

Note: sample project is generated from the ASP.NET 4.5 WebApi 2 template so it includes a lot of functionality that's not directly related to Alexa Speechlets, but it does make make for a complete Web API project.

Alternatively you can host your app and the AlexaSkillsKit.NET library in any other web service framework like ServiceStack.

How it works

SpeechletService class

To handle Alexa requests an instance of SpeechletService is used. This is the main entry point for all operations involved in handling incoming requests.

For convenience and backward compatibility both Speechlet and SpeechletAsync now derive from SpeechletBase base class, which provides built-in SpeechletService instance and wraps most common operations with it. Skill authors can access this internal SpeechletService through Service property, e.g. to register additional request handlers.

Parsing request

When new request is recieved, it first needs to be parced from json string into object model represented by SpeechletRequestEnvelope class. Task<SpeechletRequestEnvelope> SpeechletService.GetRequestAsync(string content, string chainUrl, string signature) method is used for this. Request headers and body validation also takes place during this step. The SpeechletValidationException is produced in case of any validation error.

See Override request validation policy for more details on request validation. Request validation can be omitted by directly calling one of SpeechletRequestEnvelope.FromJson static methods.

Only version "1.0" of Alexa Skill API is supported. Otherwise SpeechletValidationException with SpeechletRequestValidationResult.InvalidVersion is thrown. Same is true, when calling SpeechletRequestEnvelope.FromJson methods directly.

There are a lot of different request types available for Alexa Skills. Standard requests have simple type names: "LaunchRequest", "IntentRequest", "SessionEndedRequest". All other requests are related to specific interfaces and their request type name consists of interface name and request subtype name separated by "." sign, e.g. "System.ExceptionEncountered", "Dialog.Delegate" and so on.

SpeechletRequestParser class is used to deserialize request json field to appropriate subclass of SpeechletRequest base class. By default, it has no knowledge to which class each request type should be deserialized. SpeechletRequestParser has AddInterface method to bind interface name, with specific deserializagion handler.

SpeechletRequestEnvelope currently uses it's static instance of SpeechletRequestParser for request deserialization, provided as SpeechletRequestEnvelope.RequestParser static property. Use it, if you need to register deserialization method for additional request type.

Deserialization methods for all natively supported requests are registered internally by default.

Advanced

Override request validation policy

By default, requests with missing or invalid signatures, or with missing or too old timestamps, unsupported API version (only API v"1.0" is supported), are rejected. For Application Id to be validated, your skill needs to set value for SpeechletService.ApplicationId property. You can override the request validation policy if you'd like not to reject the request in certain conditions and/or to log validation failures.

/// <summary>
/// return true if you want request to be processed, otherwise false
/// </summary>
public override bool OnRequestValidation(
    SpeechletRequestValidationResult result, DateTime referenceTimeUtc, SpeechletRequestEnvelope requestEnvelope) 
{

    if (result != SpeechletRequestValidationResult.OK) 
    {
        if (result.HasFlag(SpeechletRequestValidationResult.NoSignatureHeader)) 
        {
            Debug.WriteLine("Alexa request is missing signature header, rejecting.");
            return false;
        }
        if (result.HasFlag(SpeechletRequestValidationResult.NoCertHeader)) 
        {
            Debug.WriteLine("Alexa request is missing certificate header, rejecting.");
            return false;
        }
        if (result.HasFlag(SpeechletRequestValidationResult.InvalidSignature)) 
        {
            Debug.WriteLine("Alexa request signature is invalid, rejecting.");
            return false;
        }
        else 
        {
            if (result.HasFlag(SpeechletRequestValidationResult.InvalidTimestamp)) 
            {
                var diff = referenceTimeUtc - requestEnvelope.Request.Timestamp;
                Debug.WriteLine("Alexa request timestamped '{0:0.00}' seconds ago making timestamp invalid, but continue processing.",
                    diff.TotalSeconds);
            }
            return true;
        }
    }
    else 
    {      
        var diff = referenceTimeUtc - requestEnvelope.Request.Timestamp;
        Debug.WriteLine("Alexa request timestamped '{0:0.00}' seconds ago.", diff.TotalSeconds);
        return true;
    }            
}