{"id":15524365,"url":"https://github.com/codeforequity-at/botium-connector-directline3","last_synced_at":"2025-04-23T07:31:35.448Z","repository":{"id":56081231,"uuid":"131757123","full_name":"codeforequity-at/botium-connector-directline3","owner":"codeforequity-at","description":"Botium Connector for Bot Framework Direct Line 3 API","archived":false,"fork":false,"pushed_at":"2023-12-12T16:03:20.000Z","size":343,"stargazers_count":4,"open_issues_count":1,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-29T22:41:20.162Z","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":"2018-05-01T19:59:23.000Z","updated_at":"2022-04-25T14:31:26.000Z","dependencies_parsed_at":"2024-06-19T01:35:22.541Z","dependency_job_id":"49eef285-b633-464c-87c2-7def08e50865","html_url":"https://github.com/codeforequity-at/botium-connector-directline3","commit_stats":{"total_commits":92,"total_committers":8,"mean_commits":11.5,"dds":0.6521739130434783,"last_synced_commit":"6d7dcf91424558ffe8e94bd92b18b00e73abbf14"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-directline3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-directline3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-directline3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-directline3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeforequity-at","download_url":"https://codeload.github.com/codeforequity-at/botium-connector-directline3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250391292,"owners_count":21422875,"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:05.206Z","updated_at":"2025-04-23T07:31:35.427Z","avatar_url":"https://github.com/codeforequity-at.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Botium Connector for Bot Framework Direct Line 3 API\n\n[![NPM](https://nodei.co/npm/botium-connector-directline3.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/botium-connector-directline3/)\n\n[ ![Codeship Status for codeforequity-at/botium-connector-directline3](https://app.codeship.com/projects/b55f7630-3017-0136-d8f8-0a3261184ed0/status?branch=master)](https://app.codeship.com/projects/288502)\n[![npm version](https://badge.fury.io/js/botium-connector-directline3.svg)](https://badge.fury.io/js/botium-connector-directline3)\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 Microsoft Bot Framework chatbots.\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?\nThe Direct Line API 3.0, part of the Microsoft Bot Framework, enables Botium to talk to a chatbot deployed and running with the Microsoft Bot Framework.\n\nThe Direct Line version number does not correspond to the Microsoft Bot Framework version number. So this connector actually supports  __Microsoft Bot Framework v3 as well as v4__.\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\n\n## Features\n* Button, Media, Card, Form extraction.\n* Adaptive Card support. \n\n## Requirements\n\n* __Node.js and NPM__\n* a __Microsoft Bot Framework__ chatbot, and user account with administrative rights\n* a __project directory__ on your workstation to hold test cases and Botium configuration\n\n## Install Botium and Directline3 Connector\n\nWhen using __Botium CLI__:\n\n```\n\u003e npm install -g botium-cli\n\u003e npm install -g botium-connector-directline3\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-directline3\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## Connecting Microsoft Bot Framework to Botium\n\nYou have to connect the Direct Line channel (with version 3.0) in Azure Portal and obtain the secret - see [here](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-directline) for instructions.\n\nOpen the file _botium.json_ in your working directory and add the secret:\n\n```\n{\n  \"botium\": {\n    \"Capabilities\": {\n      \"PROJECTNAME\": \"\u003cwhatever\u003e\",\n      \"CONTAINERMODE\": \"directline3\",\n      \"DIRECTLINE3_SECRET\": \"\u003cdirectline secret\u003e\"\n    }\n  }\n}\n```\n\nTo check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:\n\n```\n\u003e botium-cli emulator\n```\n\nBotium setup is ready, you can begin to write your [BotiumScript](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html) files.\n\n## Finetuning Directline3 Activity\n\nFor finetuning the [Activity object](https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0#activity-object) sent to your bot, you can use the [UPDATE_CUSTOM logic hook](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#update-custom). This example will add some custom values to the [channelData](https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-channeldata?view=azure-bot-service-4.0):\n\n    #me\n    do some channel specific thingy ...\n    UPDATE_CUSTOM SET_ACTIVITY_VALUE|channelData|{\"channelData1\": \"botium\", \"channelData2\": \"something else\"}\n\nThe parameters are:\n1. SET_ACTIVITY_VALUE\n2. The path to the activity field\n3. The value of the activity field\n\nAnother option for having full control over the activity is to use the **DIRECTLINE3_ACTIVITY_TEMPLATE** capability. It is a JSON structure used as a template when sending an activity to the bot.\n\n```\n    ...\n    \"DIRECTLINE3_ACTIVITY_TEMPLATE\": {\n      \"channelData\": {\n        \"my-special-channel-data\": \"...\"\n      }\n    }\n    ...\n```\n\n\n## Supported Capabilities\n\nSet the capability __CONTAINERMODE__ to __directline3__ to activate this connector.\n\n### DIRECTLINE3_SECRET *\nThe secret for accessing your chatbot from the Azure Portal.\n\n_Note: it is advised to not add this secret to a configuration file but hand it over by environment variable BOTIUM_DIRECTLINE3_SECRET_\n\n### DIRECTLINE3_DOMAIN\nIf not using the default Direct Line endpoint, e.g. if you are using a region-specific endpoint, put its full URL here\n\n### DIRECTLINE3_WEBSOCKET\n_true or false_\nWether to use Websocket connection or HTTP polling. Usually, using Websockets is prefered, but sometimes this is not possible (maybe with blocking proxies).\n\n### DIRECTLINE3_POLLINGINTERVAL\n_in milliseconds_\nHTTP Polling interval\n\n### DIRECTLINE3_BUTTON_TYPE and DIRECTLINE3_BUTTON_VALUE_FIELD\n_Default type: event_\n\n_Default field: name_\n\nActivity fields to use for simulating button clicks by the user. Depending on your implementation, you maybe have to change the activity type or the field to use - see [here](https://docs.microsoft.com/en-us/azure/bot-service/nodejs/bot-builder-nodejs-backchannel) for some ideas.\n\nUsually, the activity type is _event_, and the button value is submitted in the _name_ field, but using those capabilities you can adapt it to your implementation.\n\n_Note: if you want to disable this, then set DIRECTLINE3_BUTTON_TYPE to \"message\" and DIRECTLINE3_BUTTON_VALUE_FIELD to \"text\", to make the button clicks appear as normal user text input_\n\n### DIRECTLINE3_GENERATE_USERNAME\n_Default: false_\n\nBotium simulates conversations with username _me_. Depending on your implementation, running multiple conversations with the same username could make them fail (for example, session handling).\n\nSetting this capability to _true_ will generate a new username (uuid) for each conversation.\n\n### DIRECTLINE3_HANDLE_ACTIVITY_TYPES\n_Default: \"message\"_\n\nActivity types to handle (either JSON array or comma separated list). All other activity types will be ignored.\n\nExample: set to \"message,event\" (or [ \"message\", \"event\" ]) to also handle Bot Framework event activities with Botium\n\n### DIRECTLINE3_ACTIVITY_VALUE_MAP\n_default: { 'event': 'name' }_\n\nWhen using activity types other than _message_, this capability maps the activity type to the activity attribute to use as message text for Botium.\n\nBy default, for _event_ activities the _name_ attribute is used as message text, for other activity types the activity type itself.\n\n### DIRECTLINE3_ACTIVITY_TEMPLATE\n_default: {}_\n\nJSON object holding the activity template used for sending activities to the bot. Can be used to hold for example channelData:\n\n    ...\n    \"DIRECTLINE3_ACTIVITY_TEMPLATE\": {\n      \"channelData\": {\n        \"kb\": \"demo\"\n      }\n    },\n    ...\n\n### DIRECTLINE3_ACTIVITY_VALIDATION\n_default: 'error'_\n\nSet to 'warning' if you want to suppress activity validation errors.\n\n### DIRECTLINE3_WELCOME_ACTIVITY\n_default: empty_\n\nSend some activity upfront to start a session. Can be used to simulate the webchat/join event.\n\n    ...\n    \"DIRECTLINE3_WELCOME_ACTIVITY\": {\n      \"type\": \"event\",\n      \"name\": \"webchat/join\",\n      \"value\": {\n        \"language\": \"de-DE\"\n      },\n      \"channelData\": {\n        \"kb\": \"demo\"\n      }\n    },\n    ...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-directline3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-directline3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-directline3/lists"}