Reminders are an important part of the customer’s daily routine for various events and tasks. With this feature, you can offer reminders to customers in your skill to make it more engaging to use.
This blog will cover will how to access reminder operations such as: GET, UPDATE and DELETE when the customer is out of session, or using another web app. With this process, you can make changes to a reminder that is specific to the customer.
For example: You have developed a “Football Reminder” skill which will remind user about football matches for user to watch it but due to some issues some matches got postponed to next day. Now you can send updated reminder message to reminder skill from your web application to inform user about this change.
It's important to keep in mind that reminders can only be created while using skill but reminders can be updated, edited or deleted from outside reminder skill like web application.
How to access “reminder operations” from outside skill
Use skill messaging to send updated details to the reminder skill
Step 1: Retrieve client ID & client secret
To call the Skill Messaging API, you need to use client ID and client secret to generate an access token.
You can get the client ID and client secret from the permission section or you can use the below ASK CLI v2 command:
$ ask smapi get-skill-credentials -s {skill Id} > credentials.json
Step 2: Generate an access token to call the Skill Messaging API (SMAPI).
The Skill Messaging API (SMAPI) is used to send message requests to skill. Web application can send messages to reminder skill to update or delete existing reminder. To send message to reminder skill from web application it requires an access token.
To obtain an access token, the developer must make a POST request on an HTTPS
connection. These requests also require the client ID and client secret values for you skill which you can save in backend server.
Request Format to Obtain Access token :
API Header:
POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Body Syntax :
grant_type=client_credentials&client_id=(clientID)&client_secret=(clientSecret)&scope=alexa:skill_messaging
Response Body Syntax:
{
"access_token": "Atc|MQEWYJxE….”,
"expires_in": 3600,
"scope": "alexa:skill_messaging",
"token_type": "Bearer"
}
Step 3: Send message using Skill Messaging API
Request format to send message:
POST /v1/skillmessages/users/{user ID} HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer <<Access token retrieve in First step>>
Content-Type: application/json;
Body Syntax:
{
"data":{
“operation”: “GET”
“alertToken”: “806d8d7d-f45a-4779-91d8-c56fb6efca93”
},
"expiresAfterSeconds": 36000
}
This will send the alert token and operation message to the reminder skill about a particular user account with request type of “Messaging.MessageReceived”.
Step 4: Call the Reminder API when out of session
Now you can make a reminder operation like GET, UPDATE, and DELETE using the alertToken received in the second step.
Sample Code :
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, then we return thee 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 thee reminder, we need to retrieve it from the service
reminder = await client.getReminder(alertToken);
console.log(`[INFO] reminder: ${JSON.stringify(reminder)}`);
// changing the text content of the reminder
reminder.alertInfo.spokenInfo.content[0].text = "This is new reminder message";
// sending it to be updated
const reminderResponse = await client.updateReminder(alertToken, reminder);
console.log(`[INFO] reminderResponse: ${JSON.stringify(reminderResponse)}`);
break;
}
}
catch (error) {
console.log(error)
}
}
}
Conclusion
This walk through covered the steps required to access the Reminder API operations (GET, UPDATE, and DELETE) when out of session. By implementing this feature, you can dynamically update reminders in your skill, which in turn makes your skill more engaging for customers to use.
