.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:
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:
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/
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.
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 ISpeechletWithContextAsync
:
public interface ISpeechletWithContextAsync
{
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 ISpeechletWithContext
interface:
public interface ISpeechletWithContext
{
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
orIAudioPlayerSpeechlet
for "AudioPlayer." and "PlaybackController." requests.IDisplaySpeechletAsync
orIDisplaySpeechlet
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.
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.
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.
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.
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;
}
}
The original author of AlexaSkillsKit.NET is:
The current authors and maintainers are:
Thank You to library contributors (in alphbetical order):
- Ahmed Osman
- Chris Pauly
- dg-racing
- Dustin Masters
- Eric Jernigan
- Jasson Moya
- Jayson Helseth
- Marcus Braun
- Matt Becker
- Robert Mroch
- ruppert92
- Sergey Greenko
- Stefan Negritoiu
- vp123456
Contributor License Agreement:
https://cla-assistant.io/AreYouFreeBusy/AlexaSkillsKit.NET