{"id":15524356,"url":"https://github.com/codeforequity-at/botium-connector-alexa-avs","last_synced_at":"2025-07-31T05:02:33.114Z","repository":{"id":55547893,"uuid":"160366070","full_name":"codeforequity-at/botium-connector-alexa-avs","owner":"codeforequity-at","description":"Botium Connector for Amazon Alexa with AVS","archived":false,"fork":false,"pushed_at":"2022-01-24T11:41:04.000Z","size":582,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-27T12:50:00.481Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.botium.at","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/codeforequity-at.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":"2018-12-04T13:59:31.000Z","updated_at":"2022-01-19T18:24:09.000Z","dependencies_parsed_at":"2022-08-15T03:00:32.189Z","dependency_job_id":null,"html_url":"https://github.com/codeforequity-at/botium-connector-alexa-avs","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-alexa-avs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-alexa-avs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-alexa-avs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-alexa-avs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeforequity-at","download_url":"https://codeload.github.com/codeforequity-at/botium-connector-alexa-avs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250391083,"owners_count":21422840,"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":[],"created_at":"2024-10-02T10:51:03.792Z","updated_at":"2025-04-23T07:31:31.026Z","avatar_url":"https://github.com/codeforequity-at.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Botium Connector for Amazon Alexa with AVS\n\n[![NPM](https://nodei.co/npm/botium-connector-alexa-avs.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/botium-connector-alexa-avs/)\n\n[ ![Codeship Status for codeforequity-at/botium-connector-alexa-avs](https://app.codeship.com/projects/f379ece0-ee76-0136-6e85-5afc45d94643/status?branch=master)](https://app.codeship.com/projects/320125)\n[![npm version](https://badge.fury.io/js/botium-connector-alexa-avs.svg)](https://badge.fury.io/js/botium-connector-alexa-avs)\n[![license](https://img.shields.io/github/license/mashape/apistatus.svg)]()\n\nThis is a [Botium](https://github.com/codeforequity-at/botium-core) connector for testing your Amazon Alexa Skills.\n\n__Did you read the [Botium in a Nutshell](https://medium.com/@floriantreml/botium-in-a-nutshell-part-1-overview-f8d0ceaf8fb4) articles ? Be warned, without prior knowledge of Botium you won't be able to properly use this library!__\n\n## How it works ?\nA virtual Alexa device is registered to be used in testing, and it Works the same ways as a physical Alexa device. It is not bound to any Alexa Skill, so you have to activate your Alexa skill with its activation utterance.\n\nThe steps for Botium to run a conversation with an Alexa skill are:\n\n* Converts [BotiumScript text](hhttps://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html) to speech ([Botium Speech Processing](https://github.com/codeforequity-at/botium-speech-processing), [Cloud Speech-to-Text API](https://cloud.google.com/text-to-speech/) or [Amazon Polly](https://aws.amazon.com/polly))\n* Asks Alexa with [Amazon AVS](https://developer.amazon.com/de/docs/alexa-voice-service/get-started-with-alexa-voice-service.html)\n* Converts answer to text ([Botium Speech Processing](https://github.com/codeforequity-at/botium-speech-processing), [Cloud Text-to-Speech API, aka Cloud Speech API](https://cloud.google.com/speech-to-text/) or [Amazon Transcribe](https://aws.amazon.com/transcribe/))\n* Makes [BotiumScript assertions](hhttps://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#using-asserters)\n\n_**Warning 1**: TTS and STT can translate wrong. And so the test will fail, even if Alexa works well.\nGoogle STT handles this problem more sophisticated. See ALEXA_AVS_STT_GOOGLE_CLOUD_SPEECH_SEND_TEXT_AS_PHRASE_HINT Capability. Another option is to use a homophones list to translate utterances always recognized wrong (\"let us\" vs \"lettuce\" ...), see ALEXA_AVS_STT_HOMOPHONES capability below._\n\n_**Warning 2**: When using the cloud-based APIs, there are costs involved.Please check the pricing of the choosen cloud APIs._\n\nIt can be used as any other Botium connector with all Botium Stack components:\n* [Botium CLI](https://github.com/codeforequity-at/botium-cli/)\n* [Botium Bindings](https://github.com/codeforequity-at/botium-bindings/)\n* [Botium Box](https://www.botium.ai)\n\nThe Alexa skill to test doesn't have to be published - it can be tested while still in \"development mode\", making this connector the perfect choice for __Continuous Testing in CI Pipelines__.\n\n## Requirements\nFor Text-To-Speech and Speech-To-Text, this connector currently supports [Botium Speech Processing](https://github.com/codeforequity-at/botium-speech-processing) as well as cloud services by Amazon and Google. You only have to configure **one** of them.\n\n### Node.js v10\nNode.js v8 required, but Node.js v10 recommended because Http2 module of Node.js (AVS uses HTTP2) \n\n### Botium Speech Processing\n\nPlease see  [Botium Speech Processing repository](https://github.com/codeforequity-at/botium-speech-processing) for installation instructions.\n\n### Google Cloud Text-to-Speech API\n1. [Select or create](https://console.cloud.google.com/project) a Cloud Platform project\n2. [Enable billing](https://support.google.com/cloud/answer/6293499#enable-billing) for your project (free tier available).\n3. [Enable](https://console.cloud.google.com/flows/enableapi?apiid=texttospeech.googleapis.com) the Google Cloud Text-to-Speech API.\n4. [Set up authentication with a service account](https://cloud.google.com/docs/authentication/getting-started) so you can access the API from your local workstation.\n    1. Make sure to select _Owner_ or _Cloud Speech Service Agent_ as role\n5. **Save the JSON credentials file, you will need it later.**\n\n### Google Cloud Speech-to-Text API\n* Same steps as in Google Cloud Text-to-Speech API, just other API\n* It is recommended that Speech-to-Text and Text-to-Speech API are sharing the same project and the same credentials\n\n### Amazon Polly\n[See steps](https://docs.aws.amazon.com/polly/latest/dg/setting-up.html)  \n\nIn short:\n* [Create an IAM user](https://console.aws.amazon.com/iam/) (see [here](https://docs.aws.amazon.com/de_de/IAM/latest/UserGuide/id_users_create.html) for help)\n  * Important: choose _Programmatic access_ as access type\n  * **Note access key and secret, you will need it later**\n* Choose _Attach existing policies to user directly_ to give permissions _AmazonPollyFullAccess_\n  * Feel free to use finer grained policies if you know what you are doing\n\n### Amazon Transcribe\n_Amazon Transcribe is **very slow** for our usecase, use Botium Speech Processing or Google Cloud Speech-to-Text API if possible_\n\n_Amazon Transcribe only worked for **english language** in our tests_\n\n* [Create an S3 Bucket](https://console.aws.amazon.com/s3/)\n  * Botium uses default name _botium-connector-alexa-avs_\n* Amazon Polly and Amazon Transcribe are sharing the same IAM user by default (can be changed in botium.json later)\n* Add existing policies _AmazonTranscribeFullAccess_ and _AmazonS3FullAccess_ to this user\n  * Feel free to use finer grained policies if you know what you are doing\n\n### Amazon AVS API of the Product to test\n\nIn the [Alexa Voice Service Developer console](https://developer.amazon.com/alexa/console/avs/home), you have to register a virtual Alexa device and enable [code-based linking](https://developer.amazon.com/de-DE/docs/alexa/alexa-voice-service/code-based-linking-other-platforms.html).\n\n1. Follow [**Step 1: Enable CBL**](https://developer.amazon.com/de/docs/alexa-voice-service/code-based-linking-other-platforms.html#step1)\n2. **note your \"Client ID\", the \"Client secret\" and your \"Product ID\", you will need it later**\n\n## Preparing Botium Capabilities\n\nThe connector repository includes a tool to compose the Botium capabilities (including private keys, access tokens etc). Create a project directory of your choice, and follow the steps below.\n\n### 1. Prepare amazonConfig.json\n\n_Note: If you use Botium Box, then this step is optional. You can import the created amazonConfig.json in Botium Box, or you enter the values (AVS Product ID, Client ID...) in the Botium Box connector wizard._\n\n* Copy **AVS \"Client ID\", the \"Client secret\" and your \"Product ID\"** from steps above (Amazon AVS API of the Product to test) to a file named amazonConfig.json (see sample in cfg folder of this repository):\n* When using Amazon Transcibe / Amazon Polly:\n    * Set region you want to use (Be aware, a region has not all APIs. For example eu-west-1 has Polly, Transcribe, and S3 too)\n    * Copy Access Key ID, and Secret Access Key from steps above  (Amazon Polly, Amazon Transcribe)\n* When using Amazon Transcibe\n    * Create a bucket in S3, or use an existing one. \n\n```\n{\n  \"deviceInfo\": {\n    \"clientId\": \"xxx_required_for_AVS\",\n    \"clientSecret\": \"xxx_required_for_AVS\",\n    \"productId\": \"xxx_required_for_AVS\"\n  },\n  \"region\": \"xxx_optional_Polly_or_Transcribe\",\n  \"accessKeyId\": \"xxx_optional_Polly_or_Transcribe\",\n  \"secretAccessKey\": \"xxx_optional_Polly_or_Transcribe\",\n  \"bucketName\": \"xxx_optional_Polly_or_Transcribe\"\n}\n\n```\n\n### 2. Prepare googleConfig.json (Optional)\n\nCopy and rename Google Cloud JSON credentials to a file named googleConfig.json. (Suppose Speech-to-Text and Text-to-Speech API are sharing the same project)\n\n```\n{\n  \"type\": \"service_account\",\n  \"project_id\": \"xxx\",\n  ...\n}\n\n```\n\n### 3. Run the \"Botium Connector Alexa AVS Initialization Tool\"\n\nThere are several ways of running this tool, depending on how you installed it:\n\nWhen you are using the Botium CLI, then just run\n```\n\u003e botium-cli init-alexa-avs\n```\n\nWhen you installed the NPM package for this repository, then run\n```\n\u003e botium-connector-alexa-avs-init\n```\n\nWhen you cloned or downloaded this repository, and you are in the \"samples\" folder, then run\n```\n\u003e npm run init-alexa-avs\nor\n\u003e ./node_modules/.bin/botium-connector-alexa-avs-init\n```\n\nIf you use **Botium Box**, you dont have to use this tool - follow the suggested steps, you will be presented a hyperlink you have to open in your browser to connect the Botium virtual device to your Amazon account.\n\n### 4. Use the generated botium.json\nA file named botium.json is generated containing the required capabilities to be used with Botium.\n\n_You can remove the amazonConfig.json and googleConfig.json now_\n\n## Supported Capabilities\n\nSet the capability __CONTAINERMODE__ to __alexa-avs__ to activate this connector.\n\n### ALEXA_AVS_AVS_CLIENT_ID\nSee json downloaded from AVS\n\n### ALEXA_AVS_AVS_CLIENT_SECRET\nSee json downloaded from AVS\n\n### ALEXA_AVS_AVS_REFRESH_TOKEN\nThe simpliest way to acquire it, is the initialization tool described above\n\n### ALEXA_AVS_AVS_LANGUAGE_CODE\nLanguage setting for Alexa. Example: en_US\n\n### ALEXA_AVS_STT_HOMOPHONES\nThis connector uses speech recognition for turning the output speech coming back from Alexa into text. This process is not perfect, even with the best STT engines available - to compensate for this, homophones can be specified for errors that occur when a reply from Alexa is misunderstood. The text will be replaced in actual responses from the virtual Alexa device.\n\nHomophones lists can be specified as JSON lists or as CSV, embedded in botium.json or as an external file.\n\n**Specify in botium.json**\n```\n  \"ALEXA_AVS_STT_HOMOPHONES\": {\n    \"lettuce\": [\"let us\"],\n    \"fairy\": [\"ferry\", \"fair I\"]\n  }\n```\n\n**Specify in botium.json as CSV text**\n```\n  \"ALEXA_AVS_STT_HOMOPHONES\": \"lettuce,let us\\r\\nfairy,ferry,fair I\"\n```\n\n**Point to homophones file in botium.json**\n```\n  \"ALEXA_AVS_STT_HOMOPHONES\": \"./homophones.txt\"\n```\n_homophones.txt:_\n```\nlettuce,let us\nfairy,ferry,fair I\n```\n\n### Capabilities for Speech-To-Text\n\n#### ALEXA_AVS_STT_URL\n\n#### ALEXA_AVS_STT_PARAMS\n\n#### ALEXA_AVS_STT_METHOD\n\n#### ALEXA_AVS_STT_BODY\n\n#### ALEXA_AVS_STT_HEADERS\n\n#### ALEXA_AVS_STT_TIMEOUT\n\n#### ALEXA_AVS_STT_SEND_TEXT_AS_PHRASE_HINT\n_Default: true_\n\nAfter we got speech response from Alexa, and we are sending it to Google STT, there is a possibility to send \nthe expected answer with it. Google will use this as [hint](https://cloud.google.com/speech-to-text/docs/basics#phrase-hints).\n\nIf this flag is true, then the test is not strict. It can accept small differences between answer of Alexa, and our expectations in testcase. Because Google STT corrects the difference.\n\nIf this flag is false, then the test is strict. A test can fail even if the answer of Alexa, and our expectations in testcase are the same. Just because Google STT doesn't translate well.\n\n#### ALEXA_AVS_STT_SEND_TEXT_AS_PHRASE_HINT_USE_NEGATED\n_Default: true_\n\nThe utterance is negated\n```\n#me\nhi!\n\n#bot\n!goodbye\n``` \n\nThen it will be send as expected answer to Google STT, expect this flag is false.\n\n\n### Capabilities for Text-To-Speech\n\n#### ALEXA_AVS_TTS_URL\n\n#### ALEXA_AVS_TTS_PARAMS\n\n#### ALEXA_AVS_TTS_METHOD\n\n#### ALEXA_AVS_TTS_BODY\n\n#### ALEXA_AVS_TTS_HEADERS\n\n#### ALEXA_AVS_TTS_TIMEOUT\n\n## Open Issues and Restrictions\n* If a text is very long (more thousand), then connector dies because AVS error. Long messages should be sent in chunks.\n* Stream/connection create/close optimalization. Create/close global, for dialog, or for question-answer pair?\n* Auth token lifetime is 1h. Deal with it. (Acquire it frequently, or catch error, and refresh token)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-alexa-avs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-alexa-avs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-alexa-avs/lists"}