Turn Alexa into Your Personal Messaging Assistant
Do you want to have an assistant to check for unread SMS messages, read them aloud and let you reply to the sender? Read on!
Join the DZone community and get the full member experience.Join For Free
Do you want to have an assistant to check for unread SMS messages, read them aloud and let you reply to the sender without the need of using your phone or touching a single button on a device? If yes, go on to read this article as we will discuss developing an application to perform such a task.
In this tutorial, we will walk through the necessary steps to develop an Alexa skill that links to your RingCentral account and perform the following tasks.
Ask a user to log in to their RingCentral account.
Fetch the user’s name and phone number.
Fetch unread SMS messages.
Read aloud each SMS message and let the user decide to a) Reply to the sender with a text message. b) Listen to the next message.
Mark an unread message as read after reading the message.
- You must have a RingCentral developer account. If you don’t have one, click here to create a free developer account.
- You must have an AWS developer account. If you don’t have one, click here to create a free account.
You must have basic knowledge about how to create an Alexa Skill Kit and AWS Lambda function. If you are new to Alexa Skill development, click here to get started before moving on to read this article.
Note that the code snippets shown in this article are just for illustrations and may not work directly with copy and paste. We recommend you download the entire project from here.
You may also like: Smart Home Tutorial: ESP8266, Alexa, and Amazon Echo
Create a RingCentral App
Log in to your RingCentral developer account and click on the Create App button to create a new app.
Enter the application name and description.
Specify the application type and choose the platform type as shown below:
Add required permissions and provide the OAuth redirect URI. For now, we can leave the OAuth redirect URI field blank. The redirect URI will be obtained from the Account Linking section below.
Finally, click the Create button to complete the app creation process. At the application dashboard, copy the App Key and App Secret credentials and keep them in a safe place so we can use them later.
If you want to learn more about creating a RingCentral application. Please refer to this getting started document for details.
Create an AWS Lambda Function for Alexa Skill
We assumed that you already know how to create a Lambda function for Alexa skill so we won’t discuss in detailed how to create one in this tutorial. If you don’t know where to start, please refer to this document for detailed instructions.
When creating a Lambda function, provide all the mandatory information and choose Node JS 6.10 for the Runtime option.
You will also need to add the following key/value parameters to the function’s Environment variables.
- RC_APP_SERVER_URL: https://platform.devtest.ringcentral.com.
- AppID: the value will be obtained when we create an Alexa Custom Skill in the next section.
- RC_APP_SECRET: the RingCentral App Secret obtained from the previous section.
- RC_APP_KEY: the RingCentral App Key obtained from the previous section.
At the Lambda function code section, select “Upload a Zip file” from the Code entry type dropdown list. We will implement the code and upload the files later.
Create a New Alexa Custom Skill
Log in to your Amazon Developer account and open your skills list. Click on the Add a New Skill button on the upper right corner of the page. On the Create New Skill page, set the Skill Type radio button to the “Custom Interaction Model”. Set the Name to “RingCentral Messaging Skill”, and the Invocation Name to “my assistant”.
Save the app and click Next to move on to the Interaction Model form, then copy the following code block and paste it into the Intent Schema field.
Then define a set of sample utterances. Simply copy the following code block and paste it into the Sample Utterances field.
Link Your RingCentral Account
The best way to let each user login to RingCentral with their account credentials is to enable the account linking. To enable the feature, we continue from the step above by selecting the Configuration option from the Alexa skill dashboard and under the Account Linking section, select the Yes radio button option and provide the required information as shown and explained below:
- Authorization URL: Use RingCentral authorization endpoint https://platform.devtest.ringcentral.com/restapi/oauth/authorize.
- Client Id: Use the RingCentral app’s AppKey for this field.
Follow the steps below to complete the account linking settings:
- Copy the Redirect URL and paste it to the OAuth redirect URL of the RingCentral app as explained in the last step of the Create a RingCentral App section. Assumed that the user device is registered in the U.S, the https://pitangui.amazon.com/api/skill/link/XXX URL will be used.
- Set the Auth Code Grant radio button for the Authorization Grant Type
- Copy this URI and paste it into the Access Token URI field: https://platform.devtest.ringcentral.com/restapi/oauth/token.
- Copy your RingCentral app’s AppSecret and paste it into the Client Secret field.
Complete your Alexa Skill creation process by providing publishing information and skills beta testing so you can let other users test the skill.
Also, remember to copy the Alexa skill’s App Id (found from the Skill Information form) and paste it into the Lambda function environment variables as discussed earlier in the Create an AWS Lambda function for Alexa Skill section.
Implement Code for a Lambda Function
From a local machine, create a new project named RC-Alexa-skill.
Note: The complete source code for this skill is available for download from here.
Then install the Alexa and the RingCentral Node JS SDKs. We save the SDKs locally so that we can zip them and upload the SDKs’ files to the AWS Lambda server later.
To keep things simple, we create a single file named index.js and then complete the code step by step as discussed in the following section.
From the code above, we import the SDKs and create an instance rcsdk of the RingCentral SDK. We will use the RingCentral app’s AppKey and AppSecret specified in the lambda function’s environment variables.
Important: When you publish your RingCentral app, don’t forget to change the Lambda function’s environment variables with the production server (https://platform.ringcentral.com) and app’s credentials for production!
We also get the platform instance from the SDK, so we can use it to call RingCentral APIs later.
Then we create and export a Lambda function handler. The next step is to define the handler's object and implement functions to handle Alexa’s requests.
Let us now implement each intent function and have an explanation for essential codes. Remember that the code snippets in this section may not be completed. For implementation, use the project’s code available from GitHub instead.
When a user invokes the skill (by saying “Alexa open my assistant”), the LaunchRequest function is called. First, we check if the user has authorized Amazon to request an OAuth access token for our RingCentral app.
If the access token does not exist, we return a “LinkAccount” card, displayed in the Alexa app. The card will contain a link allowing the user to authenticate on login with RingCentral.
If the access token exists, we will set the access token using the platform.auth().setData(data) method so that we can use the platform instance to call RingCentral APIs.
We continue to implement the LaunchIntent function to fetch the user’s name, direct phone number and we will keep them in the session attributes for later usage. You can save the information into e.g. AWS DynamoDB if you want to avoid calling these codes every time the user invokes the skill.
The GetUnreadTextMessageIntent function is called when the user says e.g. “get the unread message”. Inside the function, we implement code to fetch unread messages from the user’s RingCentral account. We define the params variable and specify the messageType, readStatus and the direction parameters to fetch only inbound and unread SMS messages.
The ReadTextMessageIntent function is called when the user says “next” or “next message”. Inside the function, we implement code to read an unread message from the “textMsgs” array. We also set the message status to read when reading an unread message.
The ReplyTextMessageIntent function is called when the user says “reply” or “reply message”. Inside the function, we implement code to confirm the recipient’s phone number and get ready to intake the text message from the user.
The TextMessageIntent function is called when the user says “message body” and speak out the words to be sent. Inside the function, we ask Alexa to repeat the user’s text message to confirm if Alexa heard all the words correctly. We then wait for the user to say “yes” to send the message or to say “no” to cancel the action.
The AMAZON.YesIntent function is called when the user says “yes”. Inside the function, we check the values of the recipient’s phone number and the text message before sending the message.
The AMAZON.NoIntent function is called when the user says “no”. Inside the function, we check if the user cancels the action because of the reply message was taken incorrectly. If so, we ask the user to provide the message body again.
The DoneIntent function is called when the user says “I am done”. Inside the function, we say goodbye to the user and terminate the session. We also implement AMAZON.HelpIntent function to tell the user how to use the assistant skill. Finally, we implement the Unhandled function to handle unexpected commands.
When you are done with the code, select the index.js file and the node_modules folder to compress a .zip file then upload the compressed file to your AWS Lambda project as described in the Create an AWS Lambda Function for Alexa Skill section.
Congratulations! You have just completed the implementation of a simple Alexa skill for RingCentral. There are many more features you can add to the skill to enhance both usability and functionality.
For example, implement handler states and using dialog interface, and add new intents to check for voicemails, playback voicemails, or to make a ring-out call etcetera. I will leave that to your innovation and imagination to make your messaging assistant more useful.
Published at DZone with permission of Paco Vu. See the original article here.
Opinions expressed by DZone contributors are their own.