Connected Vehicle Skills for Alexa

You can create Alexa automotive skills for connected vehicles by using the Alexa.Automotive and smart home interfaces. With your connected vehicle skill, while outside their vehicle, users can ask any Alexa device or the Alexa app to turn the engine on or off, lock or unlock the doors, and set the temperature in different zones. For example, on a cold morning, a user can ask Alexa to turn on their car and start defrosting the windshield while they're still getting ready for work. For additional automotive skill types, see Automotive Skills for Alexa.

Connected vehicle skill utterances

When you use the Alexa.Automotive and smart home interfaces, the voice interaction model is already built for you. The following examples show some user utterances for connected vehicle skills.

Alexa, lock my car.
Alexa, unlock my car.
Alexa, turn on my truck.
Alexa, start my car with PIN 1234.
Alexa, is my car running?
Alexa, switch on the rear defroster in my truck.
Alexa, set the heat to low in my car.
Alexa, charge my car to 50%.

Who can create connected vehicle skills for Alexa

You can create a connected vehicle skill if you're a developer for a cloud-connected vehicle original equipment manufacturer (OEM). Work with Amazon's Business Development team to enable voice experiences for your customers. Currently, independent developers can't create connected vehicle skills, either for their own private use or for general public use.

Prerequisites

Before you can create a connected car skill, you must meet the following prerequisites:

  • You must have an Amazon developer account to access the Alexa developer console.
  • You must have an internet-accessible endpoint to host your connected vehicle skill.
    • Most smart home developers use Amazon Web Services (AWS) Lambda to host the skill. To write your connected vehicle skill code as a Lambda function you must have an AWS account to access the AWS management console.
    • If you want to host your skill on your OEM cloud, you build a multi-capability skill (MCS).
  • You must understand JSON and one of the supported languages for AWS Lambda: Node.js, Java, Python, C#, or Go.
  • Your system must have OAuth 2.0 enabled and support the authorization-code grant flow type. For details, see Account Linking Concepts for Alexa Skills.
  • You must have a connected vehicle, such as a car with a cloud API and a TCU unit to control it.
  • The Alexa app or an Alexa-enabled device, such as an Amazon Echo.

Interfaces for connected vehicle skills

You can use the following interfaces in your connected vehicle skills.

Interface Description
Automotive.VehicleData Implement the Alexa.Automotive.VehicleData interface to identify the make, model, year, and other information about a connected vehicle.
AuthorizationController Implement the Alexa.AuthorizationController interface to request credentials from a user before you handle a directive, such as to start a car or to unlock a car door.
PowerController Implement the PowerController interface so that users can turn the vehicle on and off. You can also use the PowerController for lights and other components of the vehicle.
LockController Implement the LockController interface so the user can lock and unlock the vehicle doors.
ToggleController Implement one or more instances of ToggleController so the user can control components of the vehicle that can be set to on or off, such as the hazard lights, or the defroster. ToggleController doesn't support semantics for automotive skills.
RangeController Implement one or more instances of RangeController so the user can control components of the vehicle that take a range of values, such as the speed of the windshield wipers, or the speed of the air conditioning fan. RangeController doesn't support semantics for automotive skills.
ModeController Implement one or more instances of ModeController so the user can select pre-defined or user-saved settings. ModeController doesn't support semantics for automotive skills.
EndpointHealth Report the connectivity status of the vehicle to Alexa.
Alexa The base interface for all Alexa skills.

Steps to create a connected vehicle skill

You can create a connected vehicle skill and host it on AWS Lambda. Or, to host your skill functionality in the OEM cloud, you can build an MSC by using Alexa-host skills.

Steps to build a Lambda-hosted connected vehicle skill

To build a Lambda-hosted connected vehicle skill for your vehicle, follow the Steps to Build a Smart Home Skill with the following changes:

  • In Create the skill, Step 5, choose Connected Vehicle instead of Smart Home.
  • In Configure the service endpoint, navigate to CONNECTED VEHICLE, and then configure the service endpoint.
  • In Provide account linking information, you must prominently surface safety guidelines to users. To meet this requirement, you can add the following warning to the account linking page with an optional link to more safety information: "Warning: This skill allows you to use voice to trigger certain functions in the vehicle, like remote vehicle start and climate control. For more information, click here."

Steps to build a multi-capability connected vehicle skill

To build a multi-capability connected vehicle skill, you create a custom skill, and then add the connected vehicle capability.

Complete the following steps to build a multi-capability connected-vehicle skill. These steps create the custom skill with Alexa-hosted backend resources. You can also host your skill with personal AWS resources.

To create a custom skill in the developer console

  1. Open the Alexa developer console and log in.
  2. Click Create Skill.
  3. At the top of the Create a new skill page, for Hosting region, accept the default or choose a new US hosting region.
  4. For Skill name, enter a name.
  5. For Default language, choose a language.
  6. For Choose a model to add to your skill, select Custom.
  7. For Choose a method to host your skill's backend resources, select Alexa-Hosted (Node.js) or Alexa-Hosted (Python).
  8. Click Create Skill.
  9. On the Choose a template to add to your skill page, choose a template, and then click the Continue with template button.
    Or, click the Import skill button. For details, see Import an Alexa-hosted Skill from a Public Git Repository. After about one or two minutes, your skill appears in the console open to the Build page.
  10. In the left pane, click Invocations, and then click Skill Invocation Name.
  11. Add your skill invocation name, and then click Build Model.
    For details, see Choose the Invocation Name for a Custom Skill.
    You don't build a custom interaction model for this skill. Alexa uses the pre-built interaction model for connected vehicles.

To add the connected vehicle model to the custom skill

  1. In the left pane, click MODELS tab.
  2. Enable the Status toggle for the Connected Vehicle model, and then click Save.
  3. In the dialog box, click Save to confirm.
  4. In the left pane, click CUSTOM tab, and then click Endpoint.
  5. Under AWS Lambda ARN, copy the default Lambda endpoint and the North America endpoint.
  6. In the left pane, click CONNECTED VEHICLE.
  7. Under AWS Lambda ARN, paste the default endpoint that you copied from the custom skill into the default endpoint box.
  8. Click North America, and then paste the North America endpoint that you copied from the custom skill into the box.
  9. Click Save.
  10. In Steps to Build a Smart Home Skill, continue with the Provide account linking information step.
    You must prominently surface safety guidelines to users during the account linking flow. To meet this requirement, you can add the following warning to the account linking page with an optional link to more safety information: "Warning: This skill allows you to use voice to trigger certain functions in the vehicle, like remote vehicle start and climate control. For more information, click here."

With an Alexa-hosted skill, you code your skill directly on the Code tab in the developer console.

Discovery for connected vehicle skills

You describe endpoints that support Alexa.Automotive.VehicleData using the standard discovery mechanism described in Alexa.Discovery.

Use VEHICLE for the display category for the main vehicle endpoint. For the full list of display categories, see display categories.

Discover response example

The following example shows a Discover.Response message for a vehicle that supports the VehicleData, AuthorizationController, and PowerController interfaces for the main vehicle endpoint.

The example also includes ToggleControllers for the front and rear defrosters. The front and rear defrosters include the Alexa.Automotive.IsPartOf relationship to attach themselves to the vehicle endpoint.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the vehicle endpoint, for this example vehicle-001>",
          "additionalAttributes":  {
            "serialNumber": "<the serial number of the vehicle>"
          },
          "endpointResources": {
            "manufacturerName": {
              "@type": "text",
              "value": {
                "text": "<the manufacturer name of the vehicle>",
                "locale": "en-US"
              }
            },
            "description": {
              "@type": "text",
                "value": {
                  "text": "<a description that appears in the Alexa app>",
                  "locale": "en-US"
                }
            },
            "friendlyNames": [
              {
                "@type": "text",
                "value": {
                  "text": "<device name that appears in the Alexa app, such as car>",
                  "locale": "en-US"
                }
              },
              {
                "@type": "text",
                "value": {
                  "text": "<additional device name, such as smart car>",
                  "locale": "en-US"
                }
              }
            ]
          },
          "displayCategories": ["VEHICLE"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.Automotive.VehicleData",
              "version": "1.0",
              "configuration": {
                "year": 2020,
                "engineType":"GAS",
                "resources": {
                  "make": {
                    "@type": "text",
                    "value": {
                      "text": "Chevrolet",
                      "locale": "en-US"
                    }
                  },
                  "model": {
                    "@type": "text",
                    "value": {
                      "text": "Silverado",
                      "locale": "en-US"
                    }
                  },
                  "trim": {
                    "@type": "text",
                    "value": {
                      "text": "LTZ",
                      "locale": "en-US"
                    }
                  }
                }
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.AuthorizationController",
              "version": "1.0",
              "properties": {
                "supported": [],
                "proactivelyReported": false,
                "retrievable": false
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        },
        {
          "endpointId": "<unique ID of the endpoint, for this example front-defrost>",
          "endpointResources": {
            "manufacturerName": {
              "@type": "text",
              "value": {
                "text": "<the manufacturer name of the vehicle or component>",
                "locale": "en-US"
              }
            },
            "description": {
              "@type": "text",
                "value": {
                  "text": "front windshield defroster",
                  "locale": "en-US"
                }
            },
            "friendlyNames": [
              {
                "@type": "text",
                "value": {
                  "text": "front defroster",
                  "locale": "en-US"
                }
              }
            ]
          },
          "displayCategories": ["OTHER"],
          "cookie": {},
          "relationships": {
            "Alexa.Automotive.IsPartOf": {
              "endpointId": "<the ID of the main vehicle endpoint, for this example vehicle-001>"
            }
          },
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "Front.Defroster",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": false,
                "nonControllable": false
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Front defroster",
                      "locale": "en-US"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        },
        {
          "endpointId": "<unique ID of the endpoint, for this example rear-defrost>",
          "endpointResources": {
            "manufacturerName": {
              "@type": "text",
              "value": {
                "text": "<the manufacturer name of the vehicle or component>",
                "locale": "en-US"
              }
            },
            "description": {
              "@type": "text",
                "value": {
                  "text": "rear windshield defroster",
                  "locale": "en-US"
                }
            },
            "friendlyNames": [
              {
                "@type": "text",
                "value": {
                  "text": "rear defroster",
                  "locale": "en-US"
                }
              }
            ]
          },
          "displayCategories": ["OTHER"],
          "cookie": {},
          "relationships": {
            "Alexa.Automotive.IsPartOf": {
              "endpointId": "<the ID of the main vehicle endpoint, for this example vehicle-001>"
            }
          },
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "Rear.Defroster",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": false,
                "nonControllable": false
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Rear defroster",
                      "locale": "en-US"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Deferred responses for connected vehicle skills

For the interfaces that you support in your skill, Alexa sends a directive to your skill when a user wants to perform an action. For example, if you support the PowerController interface, Alexa sends a TurnOn directive to your skill when the user wants to turn their vehicle on, and if you support the LockController interface, Alexa sends an Unlock directive to your skill when the user wants to unlock their vehicle doors. When you handle an Alexa directive successfully, you respond with an Alexa.Response event.

For physical changes that happen quickly, such as turning on headlights, use the following workflow:

  1. Alexa sends a directive to your skill.
  2. You send a Response event to Alexa. You can send the Response event synchronously from your Lambda function or asynchronously to the Alexa event gateway.

For physical changes that happen slowly, such as turning the vehicle on or off, or locking and unlocking the vehicle doors, use the following workflow:

  1. Alexa sends a directive to your skill.
  2. Immediately you send a DeferredResponse event to Alexa. You must always send a DeferredResponse event synchronously from your Lambda function. Send your DeferredResponse event within three seconds of receiving the directive from Alexa.
  3. After the physical action completes you send a Response event to Alexa. You can send the Response event synchronously from your Lambda function or asynchronously to the Alexa event gateway. Send your Response event within 120 seconds of receiving the directive from Alexa.

In either workflow, if an error occurs while you attempt the physical change, send an ErrorResponse event instead of a Response event in the last step.

Deferred response example

The following example shows the two events that you send in response to an unlock directive. First send a synchronous DeferredResponse event. Optionally include estimatedDeferralInSeconds, the approximate time before you send your second response, in seconds.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

Then send a Response event. If you send your response event synchronously from your Lambda function, omit the scope object from the endpoint object.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}