{"id":15362128,"url":"https://github.com/stojanovic/alexa-message-builder","last_synced_at":"2025-07-18T22:32:42.173Z","repository":{"id":57175642,"uuid":"82186987","full_name":"stojanovic/alexa-message-builder","owner":"stojanovic","description":"Simple message builder for Alexa replies.","archived":false,"fork":false,"pushed_at":"2017-10-10T20:46:55.000Z","size":13,"stargazers_count":100,"open_issues_count":0,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-05T21:05:22.043Z","etag":null,"topics":["alexa","amazon-alexa","amazon-alexa-skill","builder","message"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/alexa-message-builder","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stojanovic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-16T14:05:15.000Z","updated_at":"2024-04-08T12:17:03.000Z","dependencies_parsed_at":"2022-09-03T23:31:21.420Z","dependency_job_id":null,"html_url":"https://github.com/stojanovic/alexa-message-builder","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stojanovic%2Falexa-message-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stojanovic%2Falexa-message-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stojanovic%2Falexa-message-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stojanovic%2Falexa-message-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stojanovic","download_url":"https://codeload.github.com/stojanovic/alexa-message-builder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248830793,"owners_count":21168351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alexa","amazon-alexa","amazon-alexa-skill","builder","message"],"created_at":"2024-10-01T12:58:35.206Z","updated_at":"2025-04-14T06:20:38.350Z","avatar_url":"https://github.com/stojanovic.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alexa Message Builder\n\n[![](https://travis-ci.org/stojanovic/alexa-message-builder.svg?branch=master)](https://travis-ci.org/stojanovic/alexa-message-builder)\n[![npm](https://img.shields.io/npm/v/alexa-message-builder.svg?maxAge=2592000?style=plastic)](https://www.npmjs.com/package/alexa-message-builder)\n[![npm](https://img.shields.io/npm/l/alexa-message-builder.svg?maxAge=2592000?style=plastic)](https://github.com/claudiajs/alexa-message-builder/blob/master/LICENSE)\n\nSimple message builder for Alexa response.\n\n## Installation\n\nAlexa Message Builder is available as a node module on NPM.\n\nInstall it by running:\n\n```shell\nnpm install alexa-message-builder --save\n```\n\n## Usage\n\nAfter installing the package, require it in your code:\n\n```javascript\nconst AlexaMessageBuilder = require('alexa-message-builder')\n```\n\nor with `import`* syntax:\n\n```javascript\nimport AlexaMessageBuilder from 'alexa-message-builder'\n```\n\n\\* `import` syntax is not supported in Node.js, you need to use additional library like Babel to make it work.\n\nAfter requiring it, you simply need to initialize the class, use any of available methods from the [documentation](#documentation) below and call `.get()` in the end. For Example:\n\n```javascript\nconst AlexaMessageBuilder = require('alexa-message-builder')\n\nconst message = new AlexaMessageBuilder()\n  .addText('Hello from Alexa')\n  .get()\n```\n\nwill return:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"response\": {\n    \"shouldEndSession\": false,\n    \"outputSpeech\": {\n      \"type\": \"PlainText\",\n      \"ssml\": \"Hello from Alexa\"\n    }\n  }\n}\n```\n\n## Motivation\n\nBuilding 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:\n```json\n{\n  \"version\": \"1.0\",\n  \"response\": {\n    \"shouldEndSession\": false,\n    \"outputSpeech\" : {\n      \"type\": \"PlainText\",\n      \"text\": \"Alexa message builder is a simple message builder for Alexa responses\"\n    },\n    \"card\": {\n      \"type\": \"Standard\",\n      \"title\": \"Alexa Message Builder\",\n      \"text\": \"Alexa message builder description\",\n      \"image\": {\n        \"smallImageUrl\": \"http://example.com/small-image-url.png\",\n        \"largeImageUrl\": \"http://example.com/large-image-url.png\"\n      }\n    }\n  }\n}\n```\n\nYou can write following JavaScript code:\n```javascript\nnew AlexaMessageBuilder()\n  .addText('Alexa message builder is a simple message builder for Alexa responses')\n  .addStandardCard('Alexa Message Builder', 'Alexa message builder description', {\n    smallImageUrl: 'http://example.com/small-image-url.png',\n    largeImageUrl: 'http://example.com/large-image-url.png'\n  })\n  .keepSession()\n  .get()\n```\n\nPackage can work with any Node.js project for building Alexa app. For example, it works perfectly with [Claudia Bot Builder](https://github.com/claudiajs/claudia-bot-builder):\n\n```javascript\nconst BotBuilder = require('claudia-bot-builder'),\n      AlexaMessageBuilder = require('alexa-message-builder')\n\nmodule.exports = botBuilder(message =\u003e {\n  return new AlexaMessageBuilder()\n  \t.addText('Hello from Alexa')\n    .get()\n}, {\n  platforms: ['alexa']\n})\n```\n\n## Documentation\n\nAlexa Message Builder is still not covering 100% of Alexa JSON response, but it covers the big part of it. Here's how it works:\n\nRequire the package you previously installed from NPM:\n\n```javascript\nconst AlexaMessageBuilder = require('alexa-message-builder')\n```\n\nor with `import`* syntax:\n\n```javascript\nimport AlexaMessageBuilder from 'alexa-message-builder'\n```\n\n\\* `import` syntax is not supported in Node.js, you need to use additional library like Babel to make it work.\n\nAfter requiring it, you simply need to initialize the class, use any of available methods from the [documentation](#documentation) below and call `.get()` in the end. For Example:\n\n```javascript\nconst AlexaMessageBuilder = require('alexa-message-builder')\n\nconst message = new AlexaMessageBuilder()\n  .addText('Hello from Alexa')\n  .get()\n```\n\nwill return:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"response\": {\n    \"shouldEndSession\": false,\n    \"outputSpeech\": {\n      \"type\": \"PlainText\",\n      \"text\": \"Hello from Alexa\"\n    }\n  }\n}\n```\n\n### Add output speech\n\nThis 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](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/custom-standard-request-types-reference).\n\nYou can send either plain text or [Speech Synthesis Markup Language (SSML)](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/speech-synthesis-markup-language-ssml-reference).\n\n#### Available methods\n\n- addText\n- addSSML\n\n**addText** method can receive a plain text and it returns a reference to `this` for chaining.\n\nExample:\n\n```javascript\nnew AlexaMessageBuilder()\n  .addText('A text that Alexa will use as a response')\n  .get()\n```\n\nThis method will throw an error if `text` is not provided.\n\n**addSSML** method can receive a SSML message as a string and it returns a reference to `this` for chaining.\n\nExample:\n\n```javascript\nnew AlexaMessageBuilder()\n  .addSSML('\u003cspeak\u003eThis output speech uses SSML.\u003c/speak\u003e')\n  .get()\n```\n\nThis method will throw an error if `ssmlMessage` is not provided.\n\n### Add reprompt\n\nSimilar to the output speech, reprompt supports both text and SSML, and it can be used as a response to a [LaunchRequest or IntentRequest](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/custom-standard-request-types-reference).\n\n#### Available methods\n\n- addText\n- addSSML\n\n**addRepromptText** method can receive a plain text and it returns a reference to `this` for chaining.\n\nExample:\n\n```javascript\nnew AlexaMessageBuilder()\n  .addRepromptText('A reprompt text that Alexa will use as a response')\n  .get()\n```\n\nThis method will throw an error if `text` is not provided.\n\n**addRepromptSSML** method can receive a SSML message as a string and it returns a reference to `this` for chaining.\n\nExample:\n\n```javascript\nnew AlexaMessageBuilder()\n  .addRepromptSSML('\u003cspeak\u003eThis reprompt speech uses SSML.\u003c/speak\u003e')\n  .get()\n```\n\nThis method will throw an error if `ssmlMessage` is not provided.\n\n### Add cards\n\nAlexa supports 3 different types of the cards: Simple, Standard and LinkAccount. First two types are supported by this library.\n\nCards can only be included when sending a response to a [LaunchRequest or IntentRequest](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/custom-standard-request-types-reference).\n\n#### Add Simple card\n\nSimple card is a card that contains a title and plain text content.\n\n**addSimpleCard** method can receive title and text and it returns a reference to `this` for chaining.\n\nExample:\n\n```javascript\nnew AlexaMessageBuilder()\n  .addText('A text that Alexa will use as a response')\n  .addSimpleCard('Card title', 'Card text')\n  .get()\n```\n\nThis method will throw an error if both `title` and `text` are not provided.\n\n#### Add Standard card\n\nStandard card is a card that contains a title, text content, and an image to display.\n\n**addStandardCard** method can receive title,  text and image object, and it returns a reference to `this` for chaining.\n\nExample:\n\n```javascript\nnew AlexaMessageBuilder()\n  .addText('A text that Alexa will use as a response')\n  .addStandardCard('Card title', 'Card text', {\n    smallImageUrl: 'http://example.com/small-image-url.png',\n    largeImageUrl: 'http://example.com/large-image-url.png'\n  })\n  .get()\n```\n\nThis method will throw an error if `title`, `text` and `imageObject` are not provided.\n\n### Keep the session opened\n\nAlexa session will be closed by default, if you want to keep it opened use `.keepSession()` method.\n\n**keepSession** method will keep the session opened. It doesn't require any params.\n\nExample:\n\n```javascript\nnew AlexaMessageBuilder()\n  .addText('A text that Alexa will use as a response, and session will not be closed')\n  .keepSession()\n  .get()\n```\n\n### Add session attributes\n\nAlexa 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.\n\n**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.\n\nExample:\n\n```javascript\nnew AlexaMessageBuilder()\n  .addText('A text that Alexa will use as a response, and session will not be closed')\n  .addSessionAttribute('someKey', 1)\n  .keepSession()\n  .get()\n```\n\n## TODO\n\n- [ ] Add directives\n- [ ] Add LinkAccount cards\n- [ ] Check for limits\n\n## Contribute\n\n### Folder structure\n\nThe main body of code is in the [lib](lib) directory.\n\nThe tests are in the [spec](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](spec/helpers) directory to store Jasmine helpers, that will be loaded before any test is executed.\n\n### Running tests\n\nWe use [Jasmine](https://jasmine.github.io/) 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](spec) folder. Here are some useful command shortcuts:\n\nRun all the tests:\n\n```bash\nnpm test\n```\n\nRun only some tests:\n\n```bash\nnpm test -- filter=prefix\n```\n\nGet detailed hierarchical test name reporting:\n\n```bash\nnpm test -- full\n```\n\nWe use [ESLint](http://eslint.org/) 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.\n\n## License\n\nMIT - See [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstojanovic%2Falexa-message-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstojanovic%2Falexa-message-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstojanovic%2Falexa-message-builder/lists"}