{"id":15524384,"url":"https://github.com/codeforequity-at/botium-connector-twilio-ivr","last_synced_at":"2025-04-11T03:02:06.406Z","repository":{"id":91176466,"uuid":"171666775","full_name":"codeforequity-at/botium-connector-twilio-ivr","owner":"codeforequity-at","description":"Botium Connector for IVR systems (using Twilio)","archived":false,"fork":false,"pushed_at":"2021-09-14T06:33:17.000Z","size":493,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-25T00:42:34.872Z","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-20T12:12:07.000Z","updated_at":"2021-09-03T09:52:20.000Z","dependencies_parsed_at":"2023-04-06T03:55:18.871Z","dependency_job_id":null,"html_url":"https://github.com/codeforequity-at/botium-connector-twilio-ivr","commit_stats":{"total_commits":36,"total_committers":3,"mean_commits":12.0,"dds":"0.36111111111111116","last_synced_commit":"f4a76126fc7af774721d06ba3ba9c54fc63e40a0"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-twilio-ivr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-twilio-ivr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-twilio-ivr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-twilio-ivr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeforequity-at","download_url":"https://codeload.github.com/codeforequity-at/botium-connector-twilio-ivr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248333605,"owners_count":21086199,"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:07.808Z","updated_at":"2025-04-11T03:02:06.397Z","avatar_url":"https://github.com/codeforequity-at.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Botium Connector for Twilio IVR\n\n[![NPM](https://nodei.co/npm/botium-connector-twilio-ivr.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/botium-connector-twilio-ivr/)\n\n[![Codeship Status for codeforequity-at/botium-connector-twilio-ivr](https://app.codeship.com/projects/184b7020-1d79-0137-4301-5aea4b3287ff/status?branch=master)](https://app.codeship.com/projects/329045)\n[![npm version](https://badge.fury.io/js/botium-connector-twilio-ivr.svg)](https://badge.fury.io/js/botium-connector-twilio-ivr)\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 IVR (Interactive Voice Response)\nbots by phone call.\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\nUses [Programmable Voice](https://www.twilio.com/docs/voice) of [Twilio](https://www.twilio.com/) \nto make calls. See [Pricing of Twilio](https://www.twilio.com/voice/pricing).\n\nThis connector is separated into two parts.\n* To communicate with Twilio we have to provide webhook endpoints. See Botium webhook service.     \n* The Connector 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.at)\n* The Connector, and the Webhooks are communicating via __Redis__ \n\nSupports DTMF (accepted characters: \"0123456789*#w\". w is 0,5s delay). Example:\n\n```\n#me\nBUTTON 012w345\n```\n\n\n## Limitations\n1. Twilio uses Text To Speech, and Speech To Text. A test can fail if TTS or STT is not converting the text well.\n2. It is not possible to send DTMF and speech like this:\n```\n#me\nHello\nBUTTON 1\n```\n\n3. Special fail cases:\n   * If the dialed number is wrong, or not permitted, then the testcase will fail with error\n   * If the bot answers the phone, then error handling follows Botium standards\n   * In every other case (For example he is busy, or picks up the phone but does not say anything, or number is temporary not available...) then the test will fail with timeout\n4. Flow:\n   * We expect that the bot starts the conversation. (Otherwise call initiated, but you got error while phone ringing: error sending to bot Error: Illegal state, conversation should be started by bot!)\n\n## Prerequisites\n\n* __Node.js and NPM__\n* (optional) a __Redis__ instance (Cloud hosted free tier for example from [redislabs](https://redislabs.com/) will do as a starter)\n* __Twilio Account__ (Trial account is not sufficent because [Limitations](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account#trial-account-restrictions-and-limitations)) \n    * Sign up at [Twilio](https://www.twilio.com/try-twilio)\n    * [Upgrade trial account](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account#how-to-upgrade-your-account)\n    * [Note accountSid and authToken](https://www.twilio.com/docs/voice/quickstart/node#replace-the-placeholder-credential-values) \n* __[Purchased](https://www.twilio.com/docs/voice/quickstart/node#sign-up-for-twilio-and-get-a-phone-number), or [verified](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account#verify-your-personal-phone-number) phone number__ (Otherwise you got error: The source phone number provided, xxxxxxxxxx, is not yet verified for your account. You may only make calls from phone numbers that you've verified or purchased from Twilio.) \n* __[Enabled call destination](https://www.twilio.com/console/voice/calls/geo-permissions/low-risk)__ (Otherwise you got error: \"Account not authorized to call xxxxxxxxxx. Perhaps you need to enable some international permissions: https://www.twilio.com/console/voice/calls/geo-permissions/low-risk\")\n* a __project directory__ on your workstation to hold test cases and Botium configuration    \n\n## Install Botium and Twilio IVR Connector\n\nWhen using __Botium CLI__:\n\n```\n\u003e npm install -g botium-cli\n\u003e npm install -g botium-connector-twilio-ivr\n\u003e botium-cli init\n\u003e botium-cli run\n```\n\nWhen using __Botium Bindings__:\n\n```\n\u003e npm install -g botium-bindings\n\u003e npm install -g botium-connector-twilio-ivr\n\u003e botium-bindings init mocha\n\u003e npm install \u0026\u0026 npm run mocha\n```\n\nWhen using __Botium Box__:\n\n_Already integrated into Botium Box, no setup required_\n\n## Install and Run the Botium Twilio Webhook Proxy\n\n**If the host you are running Botium can be reached from publich internet (directly or via a service like ngrok) you can skip this step**\n\nTwilio communicates with Botium by calling webhooks published locally by Botium. If the host you are running Botium is not reachable from public internet, you have to run an additional component on a host which can be reached from public internet.\n\n* Call is initiated by the Botium Connector\n* After the call is established, it is controlled by Botium Twilio Webhook Proxy via 3 webhooks\n* Botium Twilio Webhook Proxy communicates with the Botium Connector via Redis\n\nIf you are using Botium Box, then the Botium webhook service is integrated.\n\nInstallation with NPM:\n\n    \u003e npm install -g botium-connector-twilio-ivr\n    \u003e botium-twilio-ivr-proxy-cli start --help\n\nThere are several options required for running the Botium webhook service:\n\n_--port_: Local port to listen (optional, default _5001_)\n\n_--redisurl_: Redis connection url, ex \"redis://my-redis-host:6379\" \n\nBotium is providing the service, but you have to take care for connectivity and process management yourself:\n* If your server is not reachable from the internet, consider to use a service like [ngrok](https://ngrok.com/) for publishing your endpoint (If you use ngrok start it on the port of the Webhook Service)\n* For process management, logging, monitoring we recommend to use [pm2](https://pm2.keymetrics.io)\n\n## Connecting Twilio to Botium\n\nOpen the file _botium.json_ in your working directory fill it. See Supported Capabilities. \n\n```\n{\n  \"botium\": {\n    \"Capabilities\": {\n      \"PROJECTNAME\": \"\u003cwhatever\u003e\",\n      \"CONTAINERMODE\": \"twilio-ivr\",\n      \"TWILIO_IVR_ACCOUNT_SID\": \"...\",\n      \"TWILIO_IVR_AUTH_TOKEN\": \"...\",\n      \"TWILIO_IVR_FROM\": \"...\",\n      \"TWILIO_IVR_TO\": \"...\",\n      \"TWILIO_IVR_REDISURL\" : \"...\",\n      \"TWILIO_IVR_PUBLICURL\": \"...\",\n      \"TWILIO_IVR_LANGUAGE_CODE\": \"en-US\"\n    }\n  }\n}\n```\n\nBotium setup is ready, you can begin to write your [BotiumScript](https://github.com/codeforequity-at/botium-core/wiki/Botium-Scripting) files.\n\n## Checking for received SMS\n\nA common use case is to verify that an SMS has been received during the call to an IVR engine.\n\nAdd the asserter to your botium.json:\n\n```\n  ...\n  \"ASSERTERS\": [\n    {\n      \"ref\": \"CHECKTWILIOSMS\",\n      \"src\": \"botium-connector-twilio-ivr/CHECKTWILIOSMS\"\n    }\n  ]\n  ...\n```\n\nUse it in the _#end_-section to verify that an SMS has been received by the caller:\n\n    #end\n    CHECKTWILIOSMS\n\nOr check for the content of the SMS (a common pattern is to give it some time to receive the SMS, in this example 10 seconds):\n\n    #end\n    PAUSE 10000\n    CHECKTWILIOSMS welcome to our service\n\n## Supported Capabilities\n\nSet the capability __CONTAINERMODE__ to __twilio-ivr__ to activate this connector.\n\n### TWILIO_IVR_ACCOUNT_SID\n\nSee accountSid in Prerequisites\n\n### TWILIO_IVR_AUTH_TOKEN\n\nSee authToken in Prerequisites\n\n### TWILIO_IVR_FROM\n\n[Purchased](https://www.twilio.com/docs/voice/quickstart/node#sign-up-for-twilio-and-get-a-phone-number), or [verified](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account#verify-your-personal-phone-number) phone number  \n\n### TWILIO_IVR_TO\n\nArbitary telephone number. It must be [enabled](https://www.twilio.com/console/voice/calls/geo-permissions/low-risk) \n\n### TWILIO_IVR_PUBLICURL\n\nURL on which Botium (or the Botium Twilio Webhook Proxy) is reachable from public internet.\n\nIf you are using ngrok, then it looks like this: _http://xxxxxxxx.ngrok.io_\n\n### TWILIO_IVR_INBOUNDPORT and TWILIO_IVR_INBOUNDENDPOINT\n_only required when **NOT** using the Botium Twilio Webhook Proxy_\n\nLocal port and endpoint to be used for launching the webhook\n\n### TWILIO_IVR_REDISURL and TWILIO_IVR_REDIS_TOPICBASE\n_only required when using the Botium Twilio Webhook Proxy_\n\nRedis Url and base topic name for Redis subscription topic.\n\nThe default url for local redis is _redis://localhost:6379_\n\n### TWILIO_IVR_LANGUAGE_CODE\nThe language code used for the call, like 'en-US' (optional, default _en-US_) ([All language code](https://www.twilio.com/docs/voice/twiml/gather#languagetags))\n\n### TWILIO_IVR_SPEECH_MODEL\nSee [Twilio Docs](https://www.twilio.com/docs/voice/twiml/gather#speechmodel)\n\n### TWILIO_IVR_SPEECH_MODEL_ENHANCED\nSee [Twilio Docs](https://www.twilio.com/docs/voice/twiml/gather#enhanced)\n\n### TWILIO_IVR_RECORD\nRecord the call (true/false)\n\n### TWILIO_IVR_REDIAL\nNumber of redial attempts if no answer (default 5)\n\n### TWILIO_IVR_SPEECH_TIMEOUT\ntbd\n\n### TWILIO_IVR_WAIT_CALL_STARTED\ntbd\n\n### TWILIO_IVR_WAIT_CALL_COMPLETED\ntbd\n\n### TWILIO_IVR_WAIT_BOTIUM_RESPONSE\ntbd\n\n### WAITFORBOTTIMEOUT\n\nDepending on how fast your IVR responds, the default Botium timeout of 10 seconds can lead to timeout failures. Most likely you will have to increase it (see [here](https://github.com/codeforequity-at/botium-core/wiki/Botium-Configuration#waitforbottimeout) for more)\n\n### Roadmap\n* Error case fail instead of timeout\n* Increasing STT accuracy\n* Asserter to check call state \n* Cancel phone call if conversation test finished succesful\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-twilio-ivr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-twilio-ivr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-twilio-ivr/lists"}