{"id":22085583,"url":"https://github.com/nexmo/lex-connector","last_synced_at":"2025-07-24T17:31:23.848Z","repository":{"id":47136901,"uuid":"87174414","full_name":"Nexmo/lex-connector","owner":"Nexmo","description":"The Nexmo AWS Lex Connector. A multi-tenanted connector for bridging the Nexmo Voice API WebSockets and AWS Lex","archived":false,"fork":false,"pushed_at":"2024-11-24T12:10:48.000Z","size":274,"stargazers_count":13,"open_issues_count":9,"forks_count":6,"subscribers_count":21,"default_branch":"main","last_synced_at":"2024-11-24T13:20:04.446Z","etag":null,"topics":["aws","bots","extend","lex","nexmo"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nexmo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-04T10:33:14.000Z","updated_at":"2023-12-08T20:02:10.000Z","dependencies_parsed_at":"2024-05-05T14:32:33.270Z","dependency_job_id":null,"html_url":"https://github.com/Nexmo/lex-connector","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nexmo%2Flex-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nexmo%2Flex-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nexmo%2Flex-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nexmo%2Flex-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nexmo","download_url":"https://codeload.github.com/Nexmo/lex-connector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227463798,"owners_count":17778465,"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":["aws","bots","extend","lex","nexmo"],"created_at":"2024-12-01T01:15:06.661Z","updated_at":"2024-12-01T01:15:07.391Z","avatar_url":"https://github.com/Nexmo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lex Connector\n\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/Nexmo/lex-connector/heroku)\n\nYou can use the Lex Connector to connect a Vonage Voice API call to a Lex bot and then have an audio conversation with the bot.\n\n## Amazon Lex\n\nIn order to get started, you will need to have a [AWS account](http://aws.amazon.com), as well as a bot on [Amazon Lex](https://aws.amazon.com/lex/).\nAfter your bot is configured, you will need to obtain your AWS key and secret.\n\nTo find your Access Key and Secret Access Key:\n\n- Log in to your [AWS Management Console](http://aws.amazon.com).\n- Click on your user name at the top right of the page.\n- Click on the Security Credentials link from the drop-down menu.\n- Find the Access Credentials section, and copy the latest Access Key ID.\n- Click on the Show link in the same row, and copy the Secret Access Key.\n\nYou will also need your bot name, which can be found in the Settings -\u003e General on your Amazon Lex bot page, as well as the Alias of the bot, which is located in Settings -\u003e Alias.\n\n## About The Lex Connector\n\nLex Connector makes use of the [WebSockets feature](https://docs.nexmo.com/voice/voice-api/websockets) of Nexmo's Voice API. When a call is established, the API makes a websocket connection to Lex Connector and streams the audio to and from the call in real time.\n\nLex Connector then takes care of capturing chunks of speech using Voice Activity Detection to then post to the Lex Endpoint. When Lex returns audio, Lex Connector streams that back over the websocket to the call.\n\nLex Connector does not store any Lex-specific configuration or credentials: these are supplied in the NCCO, telling the Voice API to connect the call to the Connector. This is a standard `connect` function used to connect calls to WebSockets, with a few specific parameters to connect to Lex.\n\nHere is an example of the NCCO you should return to handle incoming calls:\n\n```\n[\n    {\n        \"action\": \"talk\",\n        \"text\": \"Hello, I am Lex, how can I help you?\"\n    },\n    {\n        \"action\": \"connect\",\n        \"endpoint\": [\n            {\n                \"content-type\": \"audio/l16;rate=8000\",\n                \"headers\": {\n                    \"aws_key\": \"AAAAAAAAAAAAAAAAAAAAAAAAAAA\",\n                    \"aws_secret\": \"eescOz9xisx+gx-PFU3G4AJg4NE4UExnHYaijI+o6xgNT0\",\n                    \"sensitivity\": 3\n                },\n                \"type\": \"websocket\",\n                \"uri\": \"wss://xxxxx.ngrok.io/bot/BOTNAME/alias/ALIAS/user/USER/content\"\n            }\n        ],\n        \"eventUrl\": [\n            \"http://example.com/event\"\n        ]\n    }\n]\n```\n\nThe connector provides a handler on `/answer` which will serve the contents of `example_ncco.json` to faclitate testing.\n\nThe first `talk` action is a simple way to start the call: Lex expects the user to speak first, so we need to start the conversation as one would in a phone call, with the answerer greeting the caller. You can customise this text to fit your use case.\n\nYou should look at the [range of voices available on Nexmo](https://docs.nexmo.com/voice/voice-api/ncco-reference#talk) and on Lex to select the same voice, so that it feels natural for the caller. (There is some overlap in the choice of voices available from both Nexmo and Lex.)\n\nThe next action is `connect`: this makes the call connect to the WebSocket endpoint, specifically the Lex Connector WebSocket.\n\nThe parameter `sensitivity` allows you to set the VAD (Voice Activity Detection) sensitivity from the most sensitive (value = 0) to the least sensitive (value = 3), this is an integer value.\n\nThe path portion of the uri is the same as the path to the `PostContent` [endpoint within Lex](http://docs.aws.amazon.com/lex/latest/dg/API_PostContent.html) but with your server host address, e.g. `xxxxx.ngrok.io`. Therefore you should set your BOTNAME, ALIAS and USER details as part of this URI. You can get these details from your AWS Console after you set up a new instance of Lex.\n\nWithin the headers section of the endpoint you must supply your `aws_key` and `aws_secret` that will be used to connect to Lex.\n\nThe `eventUrl` is where Nexmo will send events regarding the connection to the Lex Connector so that your application can be aware of the start and end of a session. Currently we do not share any data or events on the requests to and from Lex. The only events sent to this URL are about the start and end of the call.\n\n\n## Running LexConnector\n\nIf you wish to deploy your own version of the Lex Connector you can do so in the following ways.\n\n### Docker\n\nStart by copying the `.env.example` file over to a new file called `.env`:\n\n```bash\ncp .env.example \u003e .env\n```\n\nEdit `.env` file, set the `PORT` value where websockets connections will be established. You can then launch the Lex Connector as a Docker instance by running:\n\n```bash\ndocker-compose up\n```\n\n### Heroku\n\nYou can deploy this application to Heroku in a single click using the 'Deploy to Heroku' button at the top of this page. Or directly from the command line using the Heroku CLI:\n\n```bash\nheroku create\n```\n\nThen deploy the app:\n\n```bash\ngit push heroku master\n```\n\nOnce the app is deployed, make a note of the URL as this is what you will need to change your websocket URI to in your NCCO in order to connect the call to the Lex Connector.\n\n### Local Install\n\n\nTo run your own instance locally you'll need an up-to-date version of Python 3. Install dependencies with:\n\n```bash\npip install --upgrade -r requirements.txt\n```\n\nCopy the `.env.example` file over to a new file called `.env`.\n\n```bash\ncp .env.example \u003e .env\n```\nEdit `.env` file, set the `PORT` value where websockets connections will be established.\n\nThe port is internal to you - LexConnector assumes the service can be accessed via the default port (80/443) on the hostname you provide, with something like NGinx proxying to the port you've provided.\n\nLexConnector is a WebSocket based service, so make sure your proxy is configured to handle WebSocket connections if you have one.\n\nIf you don't wish to run a proxy in front of LexConnector, just set the port to 80.\n\n### Running the example\n\nRun the server like this:\n\n```bash\npython server.py\n```\n\nThe WebSocket URL you use in your NCCO should use the hostname of your service wherever it is running, and if you don't have SSL set up, you'll need to change the `wss` prefix to `ws`.\n\n### Interacting with Lex\n\nCall the phone number linked to your VAPI (Voice API application). What you say at the beginning depends on how the Lex bot has been set up, i.e. the Welcome intent has a few programmed utterances, you would say one of those utterances. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnexmo%2Flex-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnexmo%2Flex-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnexmo%2Flex-connector/lists"}