---
title: "Alexa"
slug: "alexa"
updated: 2024-10-25T13:45:50Z
published: 2024-10-25T13:45:50Z
canonical: "learn.servitly.com/alexa"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://learn.servitly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Alexa

Integrate the connected products with the Alexa home based assistants.

With Alexa, your customers can command the connected products by voice commands and obtain status information.

> Alexa.. set the thermostat to 21 degrees!
> 
> Alexa.. warm up the oven to 180 degrees

## Configuration

To integrate the Alexa assistant on customer's products, you need to:

1. Create (if not yet done) an account to access the [Alexa Developer Console](https://developer.amazon.com/alexa/console/ask).
2. Create an Alexa Skill Project and configure it.
3. Configure the [Alexa](https://help.servitly.com/hc/en-us/articles/10827673295901) plugin.
4. Configure the Alexa Home Assistant for the Thing Definitions you want to support.
5. Install the *Alexa* *App* on your mobile phone (Android or iOS). Note that this is required to test the Alexa skills you are going to configure.

To start using Amazon Alexa integrations your customers need:

- An account into the tenant where the Amazon Alexa plugin is configured.
- A mobile phone (Android or iOS) with the Amazon Alexa app installed and configured.
- Optionally, an Alexa Assistant-based device (e.g. Amazon Echo Show, Amazon Echo Dot).

Here you can see an overview of the elements needed to integrate a device with Alexa.![](https://cdn.document360.io/6759e9c9-3ce3-49df-965a-7231d2d9a10a/Images/Documentation/image(107).png)

As you can see, the communication between Alexa and the devices is not direct but passes through the cloud. In particular, there is a Lambda function in the middle that is responsible for receiving API calls from the Alexa cloud and routing them to the Servitly API.

Within Servitly there is an endpoint capable of interpreting API calls for Smart Home skills and obtaining information about connected devices, status, and remotely control them.

Devices that are connected to Alexa must declare a type and interfaces (capabilities).

For more details about interfaces, you can refer to the Alexa [documentation](https://developer.amazon.com/en-US/docs/alexa/device-apis/smart-home-general-apis.html).

In case you want are implementing a Custom Skill, you must configure Custom Intent capabilities only.

## Smart Home Skills Configuration

By entering the [Alexa Developer Console](https://developer.amazon.com/alexa/console/ask) you can add a new Skill by clicking on the *Create Skill* button.

Enter the name of your skill (e.g. Visentin Ovens) and then select the Smart Home and Custom boxes.

![](https://cdn.document360.io/6759e9c9-3ce3-49df-965a-7231d2d9a10a/Images/Documentation/image(108).png)

Once a skill has been created, you must configure the various pages.

### SMART HOME

Select *Payload version* to V3

In the *Default endpoint* enter the ARN of your Lambda function used by Alexa to perform API requests to the Servitly backend. Refer to the *Lamda Function Configuration* paragraph about ARN.

### MODEL

Ensure that only Smart Home is selected.

### ACCOUNT LINKING

This is the page where you must configure the account linking between Alexa and Servitly.

![](https://cdn.document360.io/6759e9c9-3ce3-49df-965a-7231d2d9a10a/Images/Documentation/image(109).png)

- **Web Authorization URI:** [https://am-alx.servitly.com/oauth/authorize](https://am-alx.servitly.com/oauth/authorize)
- **Access Token URI:** [https://am-alx.servitly.com/oauth/token](https://am-alx.servitly.com/oauth/token)
- **Client ID:** The API key you have selected within the Alexa plugin.
- **Client secret:** The secret key of the API key you have selected within the Alexa plugin.
- **Authentication Scheme:** *Credentials in request body*
- **Scope:** *user_info*

## Lambda Function

Within your AWS account, you have to create a new Lamda based on Node.js

![](https://cdn.document360.io/6759e9c9-3ce3-49df-965a-7231d2d9a10a/Images/Documentation/image(110).png)

Click the Add Trigger button, select Alexa and insert the Skill ID in order to authorize Alexa to call the Lambda function.

Here is an example of AWS Lambda you can use as a starting point. Note that, this example is based on *NodeJS*, and uses *CommonJS modules*, so you need to configure the *index.js* file instead of the **.mjs*, which is based on *ES modules*.

```javascript
// Copyright 2024 Servitly. All Rights Reserved.
//
// This script is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied.
const https = require('https');
exports.handler = async function (request, context) {
    
    function log(severity, message1, message2) {
        console.log("[" + severity + "] " + message1 + " " + message2);
    }
    
    async function handleRequest(request, context) {
        const options = {
            hostname: 'am-alx.servitly.com',
            path: '/api/smart-home',
            method: 'POST',
            port: 443,
            headers: {
                'Content-Type': 'application/json'
            },
        };
        return new Promise((resolve, reject) => {
            const req = https.request(options, res => {
                let rawData = '';
                res.on('data', chunk => {
                    rawData += chunk;
                });
                res.on('end', () => {
                    try {
                        resolve(JSON.parse(rawData));
                    } catch (err) {
                        reject(new Error(err));
                    }
                });
            });
            req.on('error', err => {
                reject(new Error(err));
            });
            req.write(JSON.stringify(body));
            req.end();
        });
    }
    
    log("DEBUG", "REQUEST", JSON.stringify(request));
    await handleRequest(request, context).then(response => {
        console.log("DEBUG", "RESPONSE", JSON.stringify(response));
        context.succeed(response);
    }).catch(error => {
        console.log("ERROR", "ERROR", JSON.stringify(error));
        context.fail(error);
    });
};
```

You can check the Monitoring tab to verify requests made to the function. Pay attention that the Monitor tab may require several minutes before display up to date logs.

## Custom Skill Configuration

In the case Smart Home skills are not enough, you can create your own custom skill. Custom skills require to configure the account linking, which is the same as for Smart Home.

You can refer to this [guide](https://developer.amazon.com/en-US/docs/alexa/custom-skills/understanding-custom-skills.html) in order to define custom skills.

Within the Custom Skill endpoint configuration, instead of a Lambda function, you can use the following direct endpoint URL.

```plaintext
https://am-alx.servitly.com/api/custom-skill
```

![](https://cdn.document360.io/6759e9c9-3ce3-49df-965a-7231d2d9a10a/Images/Documentation/image(111).png)

Remember to select "*My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority*". This beacuse the Servitly certificate is a wild card certificate.

## Home Assistant Configuration

For each thing definition, you can now configure how the product can interact with the Alexa assistant.

To configure the Home Assistant you need to:

1. Enter the Remote *Control / Home Assistants* page.
2. Select the *Thing Definition* to edit.
3. Press the Add Home Assistant button and select Alexa.
4. Configure the Devices to display in the Alexa App.

![](https://cdn.document360.io/6759e9c9-3ce3-49df-965a-7231d2d9a10a/Images/Documentation/image(112).png)

If the product is complex, you can configure multiple devices that will appear in the Alexa App as separate devices. For example, considering a heating system, you can have several zones to be controlled separately. Each device will have its own traits, and will go to interact with and control a particular aspect of the connected product.

In case the number of devices depends on the type of installation, you can choose a metric of the thing that provides the number of devices to be generated. In this case, each Device will also need to define the Index property needed to determine which Devices to enable depending on Index Device Count metric vlaue (metric.value <= device.index).

Within each Device you can configure:

- **Name**: the name to be displayed in the Alexa App. You can use placeholders to include thing properties (e.g. ${thing.name})
- **Device Type**: the type of the device to generate (e.g. Thermostat). For a complete list of available devices and their description, refer to the [Alexa documentation](https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-discovery.html#display-categories).
- **Device Name Metric**: the metric whose value can be used as device name.
- **Index**: in case of dynamic devices, the index used to enable the device according to the *Indexed Device Count Metric*.
- **Capabilities**: the list of Alexa interfaces associated to this device. Refer to the Capabilities section below.

# Capabilities

Here is the list of all capabilities you can use to integrate connected products with Alexa.

## CustomIntent

The interface allowing Alexa custom intents mapping.

With a custom intent you can map your custom skill intents on thing-definition's specific commands.

For more details you can refer to the [Alexa documentation](https://developer.amazon.com/en-US/docs/alexa/custom-skills/steps-to-build-a-custom-skill.html) page.

| PROPERTIES |
| --- |
| *Intent Name* | The name of the Alexa custom skill intent name. Type: STRING **\|** Mandatory |
| *Intent Command* | The command to be invoked when this intent is received. Type: COMMAND **\|** Optional |
| *Slot Mapping* | The mapping between custom skill slots and command parameters. Type: KEY_VALUE **\|** Optional |
| *Speech* | The text pronounced by Alexa in response to the intent. Type: STRING **\|** Optional |
| *Card Content* | The text displayed by Alexa in response to the intent. Type: STRING **\|** Optional |

## PowerController

The interface allowing users to turn their smart home devices on and off.

For more details you can refer to the [Alexa documentation](https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-powercontroller.html) page.

| PROPERTIES |
| --- |
| *ON/OFF Status Metric* | The metric providing the ON/OFF status. Type: METRIC **\|** Mandatory |
| *ON Values* | The comma-separated list of ON values. Type: STRING **\|** Mandatory |
| *Turn ON Command* | The command used to turn on the device. Type: COMMAND **\|** Optional |
| *Turn OFF Command* | The command used to turn off the device. Type: COMMAND **\|** Optional |

## TemperatureSensor

The interface for devices that sense the current temperature, such as thermostats.

For more details you can refer to the [Alexa documentation](https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-temperaturesensor.html) page.

| PROPERTIES |
| --- |
| *Temperature Metric* | The metric providing the current measured temperature. Type: METRIC **\|** Mandatory |

## ThermostatController

Functionalities for thermostat-style devices supporting both temperature setpoints and modes.

For more details you can refer to the [Alexa documentation](https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-thermostatcontroller.html) page.

| PROPERTIES |
| --- |
| *Temperature Setpoint Parameter* | The parameter used to update the temperature setpoint. Type: CONFIGURATION_PARAMETER **\|** Optional |
| *Temperature Setpoint Metric* | The metric providing the current temperature setpoint. Type: METRIC **\|** Optional |
| *Modes* | The enabled modes and optional mappings. Type: KEY_VALUE **\|** Optional **\|** Values: OFF, HEAT, COOL, ECO |
| *Mode Metric* | The metric providing the current mode. Type: METRIC **\|** Optional |
| *Mode Parameter* | The metric providing the current humidity value. Type: CONFIGURATION_PARAMETER **\|** Optional |

## Alexa App configuration

This is the final step to control your connected product through Alexa, this step generally is up to the end-users.

You can follow this [guide](https://developer.amazon.com/en-US/docs/alexa/smarthome/debug-your-smart-home-skill.html#enable-your-skill-in-the-alexa-app) to configure the Amazon Alexa App.

## Thing Discovery

By default, when the user has connected the account to the Alexa app, discovery will return all things visible to the user.

Alternatively, you can let the user decide which things should be visible in the Alexa app. To do this, you need to add a boolean property to the things, named "*assistantEnabled*." In this way, for each thing, the user is free to enable or disable each from the home assistant discovery and control.

## Submit your skill for certification

To promote your Skill to production and make it public, you must submit the Skill for certification, and this requires to:

- implement beta testing;
- complete the quesionaires about securtity and privacy;
- provide all graphic resources and texts;
- verify your brand, you must ensure that you are authorized to use the name you gave the Skill.

For a complete list of steps to perform you can ref to the [Steps to Build a Custom Skill](https://developer.amazon.com/en-US/docs/alexa/custom-skills/steps-to-build-a-custom-skill.html) documetation page.

Note that you can wait up to 30 days to get feedback from the certification team, and you will probably have to resubmit your skill to correct minor problems. Therefore, be careful to plan the release of Skill well in advance. In case you are certifying a custom skill, more time may be required by the certification team.