npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

alexa-message-builder

v1.2.0

Published

Simple builder for Alexa replies.

Downloads

894

Readme

Alexa Message Builder

npm npm

Simple message builder for Alexa response.

Installation

Alexa Message Builder is available as a node module on NPM.

Install it by running:

npm install alexa-message-builder --save

Usage

After installing the package, require it in your code:

const AlexaMessageBuilder = require('alexa-message-builder')

or with import* syntax:

import AlexaMessageBuilder from 'alexa-message-builder'

* import syntax is not supported in Node.js, you need to use additional library like Babel to make it work.

After requiring it, you simply need to initialize the class, use any of available methods from the documentation below and call .get() in the end. For Example:

const AlexaMessageBuilder = require('alexa-message-builder')

const message = new AlexaMessageBuilder()
  .addText('Hello from Alexa')
  .get()

will return:

{
  "version": "1.0",
  "response": {
    "shouldEndSession": false,
    "outputSpeech": {
      "type": "PlainText",
      "ssml": "Hello from Alexa"
    }
  }
}

Motivation

Building JSON responses manually is not fun and hard to read for a big JSON files. The main motivation for this message builder is to replace them with a simple and readable syntax. For example, instead of this JSON:

{
  "version": "1.0",
  "response": {
    "shouldEndSession": false,
    "outputSpeech" : {
      "type": "PlainText",
      "text": "Alexa message builder is a simple message builder for Alexa responses"
    },
    "card": {
      "type": "Standard",
      "title": "Alexa Message Builder",
      "text": "Alexa message builder description",
      "image": {
        "smallImageUrl": "http://example.com/small-image-url.png",
        "largeImageUrl": "http://example.com/large-image-url.png"
      }
    }
  }
}

You can write following JavaScript code:

new AlexaMessageBuilder()
  .addText('Alexa message builder is a simple message builder for Alexa responses')
  .addStandardCard('Alexa Message Builder', 'Alexa message builder description', {
    smallImageUrl: 'http://example.com/small-image-url.png',
    largeImageUrl: 'http://example.com/large-image-url.png'
  })
  .keepSession()
  .get()

Package can work with any Node.js project for building Alexa app. For example, it works perfectly with Claudia Bot Builder:

const BotBuilder = require('claudia-bot-builder'),
      AlexaMessageBuilder = require('alexa-message-builder')

module.exports = botBuilder(message => {
  return new AlexaMessageBuilder()
  	.addText('Hello from Alexa')
    .get()
}, {
  platforms: ['alexa']
})

Documentation

Alexa Message Builder is still not covering 100% of Alexa JSON response, but it covers the big part of it. Here's how it works:

Require the package you previously installed from NPM:

const AlexaMessageBuilder = require('alexa-message-builder')

or with import* syntax:

import AlexaMessageBuilder from 'alexa-message-builder'

* import syntax is not supported in Node.js, you need to use additional library like Babel to make it work.

After requiring it, you simply need to initialize the class, use any of available methods from the documentation below and call .get() in the end. For Example:

const AlexaMessageBuilder = require('alexa-message-builder')

const message = new AlexaMessageBuilder()
  .addText('Hello from Alexa')
  .get()

will return:

{
  "version": "1.0",
  "response": {
    "shouldEndSession": false,
    "outputSpeech": {
      "type": "PlainText",
      "text": "Hello from Alexa"
    }
  }
}

Add output speech

This generates the speech that Alexa will say as a reply to your question or command. It can be used as a response to a LaunchRequest or IntentRequest.

You can send either plain text or Speech Synthesis Markup Language (SSML).

Available methods

  • addText
  • addSSML

addText method can receive a plain text and it returns a reference to this for chaining.

Example:

new AlexaMessageBuilder()
  .addText('A text that Alexa will use as a response')
  .get()

This method will throw an error if text is not provided.

addSSML method can receive a SSML message as a string and it returns a reference to this for chaining.

Example:

new AlexaMessageBuilder()
  .addSSML('<speak>This output speech uses SSML.</speak>')
  .get()

This method will throw an error if ssmlMessage is not provided.

Add reprompt

Similar to the output speech, reprompt supports both text and SSML, and it can be used as a response to a LaunchRequest or IntentRequest.

Available methods

  • addText
  • addSSML

addRepromptText method can receive a plain text and it returns a reference to this for chaining.

Example:

new AlexaMessageBuilder()
  .addRepromptText('A reprompt text that Alexa will use as a response')
  .get()

This method will throw an error if text is not provided.

addRepromptSSML method can receive a SSML message as a string and it returns a reference to this for chaining.

Example:

new AlexaMessageBuilder()
  .addRepromptSSML('<speak>This reprompt speech uses SSML.</speak>')
  .get()

This method will throw an error if ssmlMessage is not provided.

Add cards

Alexa supports 3 different types of the cards: Simple, Standard and LinkAccount. First two types are supported by this library.

Cards can only be included when sending a response to a LaunchRequest or IntentRequest.

Add Simple card

Simple card is a card that contains a title and plain text content.

addSimpleCard method can receive title and text and it returns a reference to this for chaining.

Example:

new AlexaMessageBuilder()
  .addText('A text that Alexa will use as a response')
  .addSimpleCard('Card title', 'Card text')
  .get()

This method will throw an error if both title and text are not provided.

Add Standard card

Standard card is a card that contains a title, text content, and an image to display.

addStandardCard method can receive title, text and image object, and it returns a reference to this for chaining.

Example:

new AlexaMessageBuilder()
  .addText('A text that Alexa will use as a response')
  .addStandardCard('Card title', 'Card text', {
    smallImageUrl: 'http://example.com/small-image-url.png',
    largeImageUrl: 'http://example.com/large-image-url.png'
  })
  .get()

This method will throw an error if title, text and imageObject are not provided.

Keep the session opened

Alexa session will be closed by default, if you want to keep it opened use .keepSession() method.

keepSession method will keep the session opened. It doesn't require any params.

Example:

new AlexaMessageBuilder()
  .addText('A text that Alexa will use as a response, and session will not be closed')
  .keepSession()
  .get()

Add session attributes

Alexa also allows you to store some session attributes while the session is opened. To do so with a message builder use .addSessionAttribute(key, value) method.

addSessionAttribute method can receive key and value and it returns a reference to this for chaining. Key needs to be a string and value can be in other types too.

Example:

new AlexaMessageBuilder()
  .addText('A text that Alexa will use as a response, and session will not be closed')
  .addSessionAttribute('someKey', 1)
  .keepSession()
  .get()

TODO

  • [ ] Add directives
  • [ ] Add LinkAccount cards
  • [ ] Check for limits

Contribute

Folder structure

The main body of code is in the lib directory.

The tests are in the spec directory, and should follow the structure of the corresponding source files. All executable test file names should end with -spec, so they will be automatically picked up by npm test. Any additional project files, helper classes etc that must not be directly executed by the test runner should not end with -spec. You can use the spec/helpers directory to store Jasmine helpers, that will be loaded before any test is executed.

Running tests

We use Jasmine for unit and integration tests. Unless there is a very compelling reason to use something different, please continue using Jasmine for tests. The existing tests are in the spec folder. Here are some useful command shortcuts:

Run all the tests:

npm test

Run only some tests:

npm test -- filter=prefix

Get detailed hierarchical test name reporting:

npm test -- full

We use ESLint for syntax consistency, and the linting rules are included in this repository. Running npm test will check the linting rules as well. Please make sure your code has no linting errors before submitting a pull request.

License

MIT - See LICENSE