Tutorial: Update a Reminder from Outside of an Alexa Skill Session

Note: Sign in to the developer console to build or publish your skill.

The following tutorial walks you through the steps to update a user-specific reminder from outside of an Alexa skill session. For the definition of a skill session, see Manage the Skill Session and Session Attributes.

Prerequisites

Before you can update a reminder, you must have the reminder ID of the reminder you want to update. The reminder ID is the alertToken that the Alexa Reminders API returns when you create a reminder. You can also find a reminder ID by getting all reminders.

Steps to update a reminder from outside of a skill session

In the following steps, you first get the necessary credentials to call the Skill Messaging API. You then use the Skill Messaging API to send an asynchronous message to your skill. Your skill's request handler code handles the message from the Skill Messaging API and updates the reminder.

Get a client ID and client secret for your skill.
Get the user ID.
Get an access token for the Skill Messaging API.
Call the Skill Messaging API.
Update the reminder.

Step 1: Get a client ID and client secret for your skill

Before you can get an access token for the Skill Messaging API, you must have a client ID and client secret. You can get the client ID and client secret by using the developer console or by using the Alexa Skills Kit Command Line Interface (ASK CLI).

To get the client ID and client secret from the developer console

Sign in to the Alexa developer console and navigate to your skill.
On the left, under TOOLS, click Permissions.
At the bottom of the page, under Alexa Skill Messaging, copy the value from the Alexa Client ID field.
Click SHOW, and then copy the value from the Alexa Client Secret field.

To get the client ID and client secret by using the ASK CLI

At the command prompt, enter the following command.

 ask smapi get-skill-credentials -s {skill Id} > credentials.json

Step 2: Get the user ID

When you call the Skill Messaging API in Step 4, you must have the user ID of the skill user. You can get the user ID from the context.System.user.userId field of any request from Alexa during a voice interaction with the user. For the location of the user ID within the request, see System object.

Step 3: Get an access token for the Skill Messaging API

You now get an access token for the Skill Messaging API by using the client ID and client secret that you found in Step 1. To get an access token, you make a POST request.

To get an access token for the Skill Messaging API

Make a POST request by using the following format.

Header

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Body

grant_type=client_credentials&client_id={SkillClientId}&client_secret={SkillClientSecret}&scope=alexa:skill_messaging

Get the access_token from the response, which has the following syntax.

{
   "access_token":"Atc|{someToken}",
   "expires_in": 3600,
   "scope": "alexa:skill_messaging",
   "token_type": "Bearer"
}

Step 4: Call the Skill Messaging API

You now call the Skill Messaging API by using the following information:

In the path of the request, you specify the userId that you found in a user interaction in Step 2.
As the bearer token in the Authorization header of the request, you use the access_token that you found in Step 3.
In the body of the request, you specify the alertToken, which is the reminder ID mentioned in the Prerequisites.

When you call the Skill Messaging API, Alexa sends a request of type Messaging.MessageReceived to your skill. This request contains an alert token and operation that you specify in the body of the POST request to the Skill Messaging API.

To call the Skill Messaging API

Call the Skill Messaging API by using a POST request with the following format.

Header

 POST /v1/skillmessages/users/{user ID} HTTP/1.1
 Host: api.amazonalexa.com
 Authorization: Bearer <Access token retrieved in the previous step>
 Content-Type: application/json;

Body

 {
    "data":{
      "operation": "GET"   
      "alertToken": "{alertToken}"   
    },   
    "expiresAfterSeconds": 36000   
 }

Step 5: Update the reminder

You now update the reminder from within your request handler code. In your request handler code, you handle the Messaging.MessageReceived request that you sent to your skill by using the Skill Messaging API in the previous step. The request includes the alertToken of the reminder to update.

The following request handler example includes code to get, delete, and update a reminder.

const MessageReceived_Handler = {
   canHandle(handlerInput) {
   const { request } = handlerInput.requestEnvelope;
   return request.type === 'Messaging.MessageReceived'
},

async handle(handlerInput) {
    const { requestEnvelope, serviceClientFactory } = handlerInput;
    const client = serviceClientFactory.getReminderManagementServiceClient();
    const { operation, alertToken } = requestEnvelope.request.message;

    let reminder;
    console.log(`[INFO] case: ${operation}`);

    try {
      switch (operation) {
        case 'GET':

        if (alertToken === '') {
           // If no alertToken is present, we return all the reminders.
           const reminders = await client.getReminders();
           console.log(`[INFO] reminders: ${JSON.stringify(reminders)}`);
        }

        else {
           // If the alertToken is present, we return the specific reminder.
           reminder = await client.getReminder(alertToken)
           console.log(`[INFO] reminder: ${JSON.stringify(reminder)}`);
        }

        break;

    case 'DELETE':

        const res = await client.deleteReminder(alertToken);
        console.log(`[INFO] delete response: ${JSON.stringify(res)}`);

        break;

    case 'UPDATE':

        // Before updating the reminder, we need to retrieve it from the service.
        reminder = await client.getReminder(alertToken);
        console.log(`[INFO] reminder: ${JSON.stringify(reminder)}`);

        // Change the text content of the reminder.
        reminder.alertInfo.spokenInfo.content[0].text = "This is the new reminder message";

        // Send the reminder update.
        const reminderResponse = await client.updateReminder(alertToken, reminder);
        console.log(`[INFO] reminderResponse: ${JSON.stringify(reminderResponse)}`);

        break;
      }

    }

    catch (error) {
      console.log(error)
    }
  }
}

Was this page helpful?

Provide feedback

Last updated: Nov 29, 2023