node-alexa-smapi
A node.js client library for using the Alexa Skill Management API.
Table Of Contents
Obtaining Essential Credentials
In order to obtain the refreshToken
, clientId
, and clientSecret
, you'll need to follow the instructions below:
- Follow these instructions to retrieve
clientId
andclientSecret
. - Run
ask util generate-lwa-tokens
to generate a refreshToken (copy the value fromrefresh_token
and use it to initializerefreshToken
in the next step). - Create a file called
secrets.json
which should look something like:
And here is some example code to test that the credentials are valid:
const mySmapiClient = ;const mySecrets = ; mySmapiClienttokens;
See the examples part for more examples.
Documentation
Official Documentation: https://developer.amazon.com/docs/smapi/ask-cli-intro.html#smapi-intro
All methods return a promise, which either resolves to the SMAPI data received, or rejects with an error.
Constructor
// Constructor for building the SMAPI REST client.// params should be in the form: {version: "v0, or v1 (default)", region: "NA (default), EU, or FE"}.Object
Constants
// All possible base URLs. By default, the NA url is used.const BASE_URLS = NA: 'https://api.amazonalexa.com' EU: 'https://api.eu.amazonalexa.com' FE: 'https://api.fe.amazonalexa.com';
Access Tokens
This module includes operation to retrieve a SMAPI compliant (Login with Amazon) access token. Immediately after instantiation invoke alexaSmapi.tokens.refresh(params) to seed the (Authorization header) access token for all future operations.
// Constructor for building the SMAPI REST client.// params should be in the form: {version: "v0, or v1 (default)", region: "NA (default), EU, or FE"}.const alexaSmapi = ;var smapiClient = ;smapiClienttokens;
Skill Operations
Official Documentation: https://developer.amazon.com/docs/smapi/skill-operations.html
// Fetches the skill manifest associated with the skill ID.Object alexaSmapiskills // Creates a new skill associated with the vendor ID.Object alexaSmapiskills // Updates a skill's manifest with the specified skill ID.alexaSmapiskills // Retrieves the current statuc of the skillObject alexaSmapiskillsstatusString skillId // List the skills for a specified vendorId, which is a mandatory parameter.// The optional maxResults and nextToken values provide paging for the results.Object alexaSmapiskills // Deletes a skill by its skill ID.alexaSmapiskills
Interaction Model Operations
Official Documentation: https://developer.amazon.com/docs/smapi/interaction-model-operations.html
// Retrieves the interaction model for a specified skill.Object alexaSmapiinteractionModel // Retrieves the Etag for a specified skill.String alexaSmapiinteractionModel // Updates the interaction model for a specified skill.Object alexaSmapiinteractionModel // Retrieves the building status of the interaction model.Object alexaSmapiinteractionModel
Account Linking Operations
Official Documentation: https://developer.amazon.com/docs/smapi/account-linking-operations.html
// Updates the account linking detailsalexaSmapiaccountLinking // Retrieves the account linking detailsObject alexaSmapiaccountLinking // Deletes the account linking detailsalexaSmapiaccountLinking
Vendor Operations
Official Documentation: https://developer.amazon.com/docs/smapi/vendor-operations.html
// List all of the vendors associated with a user (access token).Array alexaSmapivendors
Skill Enablement Operations
Official Documentation: https://developer.amazon.com/docs/smapi/skill-enablement.html
// Enables a skill stage for the requestor. The requestor should be either a developer or the owner of the skill.// Please note that only one skill stage can be enabled for a given user at one time.alexaSmapiskillEnablement // Checks whether a skill stage is enabled or not for the requestor.alexaSmapiskillEnablementstatusString skillId String stage // Disables a skill by deleting the skill enablement.alexaSmapiskillEnablement
Skill Certification Operations
Official Documentation: https://developer.amazon.com/docs/smapi/skill-certification-operations.html
// Submit a skill for certification for potential publication.alexaSmapiskillCertification // Check status of a skill certification.// Working for v1 only as it was implemented mainly trough trial & error as operation is not documented under https://developer.amazon.com/docs/smapi/skill-certification-operations.htmlalexaSmapiskillCertificationstatusString vendorId String skillId // Withdraw a skill from the certification process.// Possible enumeration values for 'reason'// * TEST_SKILL// * MORE_FEATURES// * DISCOVERED_ISSUE// * NOT_RECEIVED_CERTIFICATION_FEEDBACK// * NOT_INTEND_TO_PUBLISH// * OTHERalexaSmapiskillCertification
Skill Testing Operations
Official Documentation: https://developer.amazon.com/docs/smapi/skill-testing-operations.html
// Used for directly testing a skill by passing the skill request object directly.Object alexaSmapiskillTesting // Used for directly testing a skill by passing the skill request object directly.Object alexaSmapiskillTesting // Used for directly testing a skill by passing the skill request object directly.Object alexaSmapiskillTesting // Simulates a skill execution.Object alexaSmapiskillTesting // Retrieves the status of the simulated skill execution.Object alexaSmapiskillTesting
Intent Request History Operations
Official Documentation: https://developer.amazon.com/docs/smapi/intent-request-history.html
// Provides aggregated and anonymized transcriptions of user speech data and intent request details for their skills, on a per-skill basis.// A skill must have at least 10 unique users per locale in a day, in order for data to be available for that locale for that day.// Here is the format for params (only the skillId is required all others are optional):// * skillId - The skillId for which utterance data is returned.// * nextToken (default: null) - Use nextToken along with the maxResults parameter to specify how many results should be loaded in the page.// * maxResults (default: 10) - Maximum number of result items (at-most and not at-least) that will be returned in the response.// * sortDirection (dafault: desc) - Valid values: asc (for ascending) or desc (for descending).// * sortField - Valid values: dialogAct.name, locale, intent.confidence.bin, stage, publicationStatus, intent.name, interactionType, or utteranceText.// * dialogAct.name (default: null) - Valid values: Dialog.ElicitSlot, Dialog.ConfirmSlot, or Dialog.ConfirmIntent.// * locale (default: null) - Valid values: All currently supported locales. Example: en-US. This filter can have multiple values and is not case-sensitive.// * intent.confidence.bin (default: null) - Valid values: HIGH, MEDIUM, OR LOW. This filter can have multiple values and is not case-sensitive.// * stage (default: null) - Valid values: live or development. This filter can have multiple values and is not case-sensitive.// * publicationStatus (default: null) - Valid values: certification or development. This filter can have multiple values and is not case-sensitive.// * utteranceText (default: null) - Valid values: Any string. This filter can have multiple values and is not case-sensitive.// * intent.name (default: null) - Valid values: Any string without white spaces. This filter can have multiple values and is not case-sensitive.// * intent.slot.name (default: null) - Valid values: Any string without white spaces. This filter can have multiple values and is not case-sensitive.// * interactionType (default: null) - This filter can have multiple values. Valid values:// * ONE_SHOT: The user invokes the skill and states their intent in a single phrase.// * MODAL: The user first invokes the skill and then states their intent.alexaSmapiintentRequests
Sample params:
const params = skillId: 'MY_SKILL_ID' maxResults: 10 sortDirection: 'desc' sortField: 'intent.confidence.bin' locale: 'en-US' locale: 'en-CA' locale: 'en-GB' locale: 'en-AU' locale: 'en-IN' 'intent.confidence.bin': 'high' 'intent.confidence.bin': 'medium' 'intent.confidence.bin': 'low' stage: 'live' stage: 'development' publicationStatus: 'certification' publicationStatus: 'development' utteranceText: 'api' utteranceText: 'a pie' utteranceText: 'ape' 'intent.name': 'testIntent' 'intent.name': 'AMAZON.HelpIntent' interactionType: 'ONE_SHOT' interactionType: 'MODAL';
Miscellaneous Functions
// Refeshes the authorization token with the access token provided.alexaSmapi // Sets the new base URL for future API calls.alexaSmapi
Custom API calls
Due to its recent release to the public, some API methods may not be covered by this module. In that case, a bunch of custom functions are available to use. They will return the response received from making the call.
// Perform a custom HEAD requestalexaSmapicustom // Perform a custom GET requestalexaSmapicustom // Perform a custom POST requestalexaSmapicustom // Perform a custom PUT requestalexaSmapicustom // Perform a custom DELETE requestalexaSmapicustom
Examples
Note that you'll always need to have a valid refreshToken
, in which you can obtain that code below:
const mySmapiClient = ;const mySecrets = ; mySmapiClienttokens;
Using Promises
const mySmapiClient = ;const mySecrets = ; mySmapiClienttokens;
Using Async/Await
const mySmapiClient = ;const mySecrets = ; { try await mySmapiClienttokens; let manifest = await smapiClientskills; console; catch error console; };