Getting started Alexa Reminder API by curl or ASK-Utils

Today the Alexa team announced to the new Reminder API. Let’s get started it 🙂

Remind Customers of Important Tasks or Events with the Reminders API

Configure Skills permission

The reminder API requires the user permission. So you have to update “permissions” settings to enable the Remidners API.

And by using ASK CLI, your skill.json have to add following section.

{
  "manifest": {
    ...
    "manifestVersion": "1.0",
    "permissions": [
      {
        "name": "alexa::alerts:reminders:skill:readwrite"
      }
    ],

alexa::alerts:reminders:skill:readwrite is the reminder API permission.

User application settings

After update your skill’s setting, you have to allow the reminders from your Alexa application.

Get API access token

The API requires API access token, so please get the parameters from yous Alexa developer console or your skill’s AWS Lambda function.You can get the token from .context.System.apiAccessToken.

Build the request by curl

You can send a request to the reminder API by following command.

curl https://api.amazonalexa.com/{path} 
 -H "Authorization:Bearer <.context.System.apiAccessTokenの値>" 
 -H 'Accept: application/json'

Register new Reminder

You can add a new reminder from your Alexa Skill by sending POST request. For example, the payload is a relative reminder. The remainder will push notification after 7200 seconds.

{
   "requestTime" : "2018-11-01T19:04:00.672" 
   "trigger": {
        "type" : "SCHEDULED_RELATIVE",
        "offsetInSeconds" : "7200",
   },
   "alertInfo": {
        "spokenInfo": {
            "content": [{
                "locale": "ja-JP",
                "text": "犬の散歩"
            }]
        }
    },
    "pushNotification" : {                            
         "status" : "ENABLED"
    }
}

List the reminders

When you send a GETrequest, you can get the skill’s remainder lists.

{
  totalCount: 4,
  alerts:[{
        "alertToken": "d877f6b7-fe34-40fe-9029-a67a3f75140f",
        "createdTime": "2018-11-01T15:44:59.336Z",
        "updatedTime": "2018-11-01T15:50:24.561Z",
        "trigger": {
          "type": "SCHEDULED_ABSOLUTE",
          "scheduledTime": "2018-11-30T07:30:00.000",
          "timeZoneId": "Asia/Tokyo",
          "offsetInSeconds": 0,
          "recurrence": null
        },
        "status": "COMPLETED",
        "alertInfo": {
          "spokenInfo": {
            "content": [
              {
                "locale": "",
                "text": "Test Reminder",
                "ssml": ""
              }
            ]
          }
        },
        "pushNotification": {
          "status": "ENABLED"
        },
        "version": "3"
      }
...

Request the API by ASK Utils

For now, the ASK SDK has not been supported the API. Unfortunately, you have to make a request by your own code. 

So I’ve made a request wrapper class in my ASK Utils library.

Please install or update the library by a npm i -S ask-utils@latest command.

Example code

The wrapper class usingasyn/await, please be careful.

const { RemidnerClient } = require('ask-utils')
// PUT new reminder
const client = new RemidnerClient(handlerInput)
const payload = {...}
client.setPayload(payload)
await client.fetch('POST')

// Lists reminder
const client = new RemidnerClient(handlerInput)
const lists = await client.fetch()

// Delete a reminder
const client = new RemidnerClient(handlerInput)
await client.fetch('DELETE', `/v1/alerts/reminders/${id}`)