{"id":15524357,"url":"https://github.com/codeforequity-at/botium-connector-dialogflow","last_synced_at":"2025-04-07T10:25:01.781Z","repository":{"id":52427888,"uuid":"139972793","full_name":"codeforequity-at/botium-connector-dialogflow","owner":"codeforequity-at","description":"Botium Connector for Google Dialogflow","archived":false,"fork":false,"pushed_at":"2024-10-04T08:55:46.000Z","size":636,"stargazers_count":13,"open_issues_count":2,"forks_count":12,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-31T08:12:09.203Z","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-07-06T10:51:43.000Z","updated_at":"2024-10-04T08:55:27.000Z","dependencies_parsed_at":"2024-10-31T15:01:43.714Z","dependency_job_id":"75c2b662-b0f7-41ab-a5a4-c9fd1f9caf43","html_url":"https://github.com/codeforequity-at/botium-connector-dialogflow","commit_stats":{"total_commits":116,"total_committers":11,"mean_commits":"10.545454545454545","dds":0.4913793103448276,"last_synced_commit":"40ff5e59ad7d16af9ae1e9fc896c41527658d6d2"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-dialogflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-dialogflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-dialogflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-dialogflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeforequity-at","download_url":"https://codeload.github.com/codeforequity-at/botium-connector-dialogflow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247633332,"owners_count":20970305,"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.951Z","updated_at":"2025-04-07T10:25:01.757Z","avatar_url":"https://github.com/codeforequity-at.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Botium Connector for Google Dialogflow\r\n\r\n[![NPM](https://nodei.co/npm/botium-connector-dialogflow.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/botium-connector-dialogflow/)\r\n\r\n[![npm version](https://badge.fury.io/js/botium-connector-dialogflow.svg)](https://badge.fury.io/js/botium-connector-dialogflow)\r\n[![license](https://img.shields.io/github/license/mashape/apistatus.svg)]()\r\n\r\nThis is a [Botium](https://github.com/codeforequity-at/botium-core) connector for testing your Dialogflow Agents.\r\n\r\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!__\r\n\r\n## How it works ?\r\nBotium runs your conversations against the Dialogflow API.\r\n\r\nIt can be used as any other Botium connector with all Botium Stack components:\r\n  * [Botium CLI](https://github.com/codeforequity-at/botium-cli/)\r\n  * [Botium Bindings](https://github.com/codeforequity-at/botium-bindings/)\r\n  * [Botium Box](https://www.botium.ai)\r\n\r\nExtracts Button, Media, Card, and NLP information (intent, entities) from Chatbot API response. Accordingly it is possible to use a corresponding [Botium Asserter](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#using-asserters).\r\n\r\n## Requirements\r\n\r\n* __Node.js and NPM__\r\n* a __Dialogflow__ agent, and user account with administrative rights\r\n* a __project directory__ on your workstation to hold test cases and Botium configuration\r\n\r\n## Install Botium and Dialogflow Connector\r\n\r\nWhen using __Botium CLI__:\r\n\r\n```\r\n\u003e npm install -g botium-cli\r\n\u003e npm install -g botium-connector-dialogflow\r\n\u003e botium-cli init\r\n\u003e botium-cli run\r\n```\r\n\r\nWhen using __Botium Bindings__:\r\n\r\n```\r\n\u003e npm install -g botium-bindings\r\n\u003e npm install -g botium-connector-dialogflow\r\n\u003e botium-bindings init mocha\r\n\u003e npm install \u0026\u0026 npm run mocha\r\n```\r\n\r\nWhen using __Botium Box__:\r\n\r\n_Already integrated into Botium Box, no setup required_\r\n\r\n## Connecting Dialogflow Agent to Botium\r\n\r\nOpen the file _botium.json_ in your working directory and add the Google credentials for accessing your Dialogflow agent. [This article](https://wiki.botiumbox.com/technical-reference/botium-connectors/supported-technologies/botium-connector-dialogflow/) shows how to retrieve all those settings.\r\n\r\n```\r\n{\r\n  \"botium\": {\r\n    \"Capabilities\": {\r\n      \"PROJECTNAME\": \"\u003cwhatever\u003e\",\r\n      \"CONTAINERMODE\": \"dialogflow\",\r\n      \"DIALOGFLOW_PROJECT_ID\": \"\u003cgoogle project id\u003e\",\r\n      \"DIALOGFLOW_CLIENT_EMAIL\": \"\u003cservice credentials email\u003e\",\r\n      \"DIALOGFLOW_PRIVATE_KEY\": \"\u003cservice credentials private key\u003e\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nTo check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:\r\n\r\n```\r\n\u003e botium-cli emulator\r\n```\r\n\r\nBotium setup is ready, you can begin to write your [BotiumScript](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#) files.\r\n\r\n## Using the botium-connector-dialogflow-cli\r\n\r\nThis connector provides a CLI interface for importing convos and utterances from your Dialogflow agent and convert it to BotiumScript.\r\n\r\n* Intents and Utterances are converted to BotiumScript utterances files (using the _--buildconvos_ option)\r\n* Conversations are reverse engineered and converted to BotiumScript convo files (using the _--buildmultistepconvos_ option)\r\n\r\nYou can either run the CLI with *[botium-cli](https://github.com/codeforequity-at/botium-cli) (recommended - it is integrated there)*, or directly from this connector (see samples/assistant directory for some examples):\r\n\r\n    \u003e botium-connector-dialogflow-cli import --buildconvos\r\n    \u003e botium-connector-dialogflow-cli import --buildmultistepconvos\r\n\r\n_Please note that you will have to install the npm packages botium-core manually before using this CLI_\r\n\r\nFor getting help on the available CLI options and switches, run:\r\n\r\n    \u003e botium-connector-dialogflow-cli import --help\r\n\r\n## Dialogflow Context Handling\r\n\r\nWhen using BotiumScript, you can do assertions on and manipulation of the [Dialogflow context variables](https://cloud.google.com/dialogflow/docs/contexts-overview).\r\n\r\n### Asserting context and context parameters\r\n\r\nFor asserting existance of context variables, you can use the [JSON_PATH asserter](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#jsonpath-asserter):\r\n\r\n**Assert output context name**\r\n\r\n    #bot\r\n    JSON_PATH $.outputContexts[0].name|*testsession*\r\n\r\n_Use the ***** for wildcard matching_\r\n\r\n**Assert context parameter \"myparameter\" for output context named \"mycontext\"**\r\n\r\n    #bot\r\n    JSON_PATH $.outputContexts[?(@.name.indexOf('mycontext') \u003e= 0)].parameters.myparameter|somevalue\r\n\r\n_Use the JSONPath filer for matching a context by name instead of index_\r\n\r\n**Assert lifespan for output context named \"mycontext\"**\r\n\r\n    #bot\r\n    JSON_PATH $.outputContexts[?(@.name.indexOf('mycontext') \u003e= 0 \u0026\u0026 @.lifespanCount \u003e 2)]\r\n\r\n### Adding context variables\r\n\r\nFor adding a context variable, you have to use the [UPDATE_CUSTOM logic hook](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#update-custom). This example will set two context variables, one with some parameters:\r\n\r\n    #me\r\n    heyo\r\n    UPDATE_CUSTOM SET_DIALOGFLOW_CONTEXT|mycontext1|7\r\n    UPDATE_CUSTOM SET_DIALOGFLOW_CONTEXT|mycontext2|{\"lifespan\": 4, \"parameters\": { \"test\": \"test1\"}}\r\n\r\nThe parameters are:\r\n1. SET_DIALOGFLOW_CONTEXT\r\n2. The name of the context variable (if already existing, it will be overwritten)\r\n3. The lifespan of the context variable (if scalar value), or the lifespan and the context parameters (if JSON formatted)\r\n\r\n## Dialogflow Query Parameters\r\n\r\nWhen using BotiumScript, you can do manipulation of the [Dialogflow query parameters](https://cloud.google.com/dialogflow/docs/reference/rest/v2beta1/QueryParameters).You have to use the [UPDATE_CUSTOM logic hook](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#update-custom). This example will add a _payload_ field with some JSON content in the query parameters:\r\n\r\n    #me\r\n    heyo\r\n    UPDATE_CUSTOM SET_DIALOGFLOW_QUERYPARAMS|payload|{\"key\": \"value\"}\r\n\r\n## Supported Capabilities\r\n\r\nSet the capability __CONTAINERMODE__ to __dialogflow__ to activate this connector.\r\n\r\n### DIALOGFLOW_PROJECT_ID\r\n\r\nGoogle project id. See [This article](https://chatbotsmagazine.com/3-steps-setup-automated-testing-for-google-assistant-and-dialogflow-de42937e57c6)\r\n\r\n### DIALOGFLOW_ENVIRONMENT\r\n\r\nDialogflow publishing environment name. See [This article](https://cloud.google.com/dialogflow/docs/agents-versions)\r\n\r\n### DIALOGFLOW_CLIENT_EMAIL\r\n_Optional_\r\n\r\nGoogle client email. See [This article](https://chatbotsmagazine.com/3-steps-setup-automated-testing-for-google-assistant-and-dialogflow-de42937e57c6)\r\n\r\nIf not given, [Google default authentication](https://cloud.google.com/docs/authentication/getting-started) will be used.\r\n\r\n### DIALOGFLOW_PRIVATE_KEY\r\n_Optional_\r\n\r\nGoogle private key. See [This article](https://chatbotsmagazine.com/3-steps-setup-automated-testing-for-google-assistant-and-dialogflow-de42937e57c6)\r\n\r\nIf not given, [Google default authentication](https://cloud.google.com/docs/authentication/getting-started) will be used.\r\n\r\n### DIALOGFLOW_LANGUAGE_CODE\r\n\r\nThe language of this conversational query. See [all languages](https://dialogflow.com/docs/reference/language).\r\nA Dialogflow Agent is multilingiual, Connector is not. But you can use more botium.json for each language.\r\n(Botium Box, or Botium CLI is recommended in this case. Botium Bindings does not support more botium.xml)\r\n\r\n### DIALOGFLOW_OUTPUT_PLATFORM\r\n\r\nSet the chat platform to get platform dependent response. See [all platforms](https://dialogflow.com/docs/reference/message-objects#text_response_2)\r\nIf you have multi platform dependent conversation, then it is the same situation as DIALOGFLOW_LANGUAGE_CODE\r\n\r\n### DIALOGFLOW_FORCE_INTENT_RESOLUTION\r\n\r\nExperimental capability.\r\n\r\nFrom a Dialogflow response the Connector can extract zero, one, or more messages. Every message will got the NLP information like intent and entities from the Dialogflow response.\r\nIf Connector extracts zero messages, then creates a dummy one, to hold the NLP information. With this flag you can turn off this feature.\r\n\r\nDefault _true_\r\n\r\n### DIALOGFLOW_BUTTON_EVENTS\r\nDefault _true_\r\n\r\nBotium simulates button clicks by using [Dialogflow \"Events\"](https://dialogflow.com/docs/events). If the payload of the button click simulation is valid JSON, it should include a [\"name\" and a \"parameters\" attribute](https://cloud.google.com/dialogflow-enterprise/docs/reference/rpc/google.cloud.dialogflow.v2#google.cloud.dialogflow.v2.EventInput), otherwise the named event without parameters is triggered.\r\n\r\nBy setting this capability to _false_ this behaviour can be disabled and a button click is sent as text input to Dialogflow.\r\n\r\n### DIALOGFLOW_QUERY_PARAMS\r\n\r\nSetting the initial [Dialogflow query parameters](https://cloud.google.com/dialogflow/docs/reference/rest/v2beta1/QueryParameters).\r\n\r\nHas to be a JSON-string or JSON-object.\r\n\r\n### DIALOGFLOW_INPUT_CONTEXT_NAME(_X)\r\n\r\nYou can use [Contexts](https://dialogflow.com/docs/contexts). They can be useful if you dont want to start the conversation from beginning,\r\nor you can set a context parameter “testmode” to make the web api behind the fulfillment react in a different way than in normal mode.\r\n\r\nIf you are using more context parameters then you have to use more Capabilities. Use a name, or number as suffix to distinguish them. (Like DIALOGFLOW_INPUT_CONTEXT_NAME_EMAIL).\r\n\r\nThis Capability contains the name of the parameter.\r\n\r\nSee also the [Sample botium.json](./samples/RoomReservation/botium.json)\r\n\r\n### DIALOGFLOW_INPUT_CONTEXT_LIFESPAN(_X)\r\n\r\nThe number of queries this parameter will remain active after being invoked.\r\n\r\nMandatory Capability.\r\n\r\n### DIALOGFLOW_INPUT_CONTEXT_PARAMETERS(_X)\r\n\r\nThis Capability contains the values of the parameter. It is a JSON structure. See [Sample botium.json](./samples/RoomReservation/botium.json)\r\n\r\nOptional Capability.\r\n\r\n### DIALOGFLOW_ENABLE_KNOWLEDGEBASE\r\n_Default: false_\r\n\r\nThis Capability enables support for [Dialogflow Knowledge Connectors](https://cloud.google.com/dialogflow/docs/knowledge-connectors). If this is set to _true_, then all knowledge bases connected to your Dialogflow agent are included in the queries. You can select individual knowledge bases by using a JSON array with the full knowledge base names, including the google project id and the knowledge base id:\r\n\r\n    ...\r\n    \"DIALOGFLOW_ENABLE_KNOWLEDGEBASE\": [ \"projects/project-id/knowledgeBases/knowledge-base-id\" ]\r\n    ...\r\n\r\n### DIALOGFLOW_FALLBACK_INTENTS\r\n_Default: ['Default Fallback Intent']_\r\n\r\nAs default the not recognized utterance will be categorized as _Default Fallback Intent_ by Dialogflow.\r\nIf you change this behavior, you can inform connector about it. Used just for analyzation.   \r\n\r\n## Additional Capabilities for NLP Analytics\r\n\r\nThe recommendation is to separate the Dialogflow agent you are using for NLP analytics from the one used for training your chatbot. There is a separate set of capabilities for connecting to an additional Dialogflow agent.\r\n\r\n### DIALOGFLOW_NLP_PROJECT_ID\r\n\r\nGoogle project id.\r\n\r\n### DIALOGFLOW_NLP_CLIENT_EMAIL\r\n\r\nGoogle client email.\r\n\r\n### DIALOGFLOW_NLP_PRIVATE_KEY\r\n\r\nGoogle private key.\r\n\r\n## Additional Capabilities for Audio Input (Speech Recognition)\r\n\r\nFor more details about audio configuration, go [here](https://cloud.google.com/speech-to-text/docs/encoding?hl=de).  \r\n\r\n### DIALOGFLOW_AUDIOINPUT_ENCODING\r\n\r\nAudio File Encoding\r\n\r\n### DIALOGFLOW_AUDIOINPUT_SAMPLERATEHERTZ\r\n\r\nAudio File Sample Rate in Hertz\r\n\r\n### DIALOGFLOW_AUDIOINPUT_CHANNELS\r\n\r\nAudio File - Count of Channels\r\n\r\n### DIALOGFLOW_AUDIOINPUT_RECOGNITION_PER_CHANNEL\r\n\r\nAudio File - Separate Recognition per Channel\r\n\r\n### DIALOGFLOW_API_ENDPOINT\r\n\r\nBy default the Dialogflow connector only works with the US (Global) region of Dialogflow, however it can be configured to connect to a region specific version of Dialogflow. This requires setting the project ID to include the location AND setting a custom API Endpoint for the specific region dialogflow instance. In this example configuration, an example of the dialogflow region would be `australia-southeast1`. List of available regions: https://cloud.google.com/dialogflow/es/docs/how/region\r\n\r\n```\r\n{\r\n  \"botium\": {\r\n    \"Capabilities\": {\r\n      \"PROJECTNAME\": \"\u003cwhatever\u003e\",\r\n      \"CONTAINERMODE\": \"dialogflow\",\r\n      \"DIALOGFLOW_PROJECT_ID\": \"\u003cgoogle project id\u003e/locations/\u003cdialogflow region\u003e\",\r\n      \"DIALOGFLOW_CLIENT_EMAIL\": \"\u003cservice credentials email\u003e\",\r\n      \"DIALOGFLOW_PRIVATE_KEY\": \"\u003cservice credentials private key\u003e\",\r\n      \"DIALOGFLOW_API_ENDPOINT\": \"\u003cdialogflow region\u003e-dialogflow.googleapis.com\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Open Issues and Restrictions\r\n* Account Linking is not supported (Consider using [Botium Connector for Google Assistant](https://github.com/codeforequity-at/botium-connector-google-assistant) if you want to test it)\r\n* Not [all](https://cloud.google.com/dialogflow-enterprise/docs/reference/rest/v2/projects.agent.intents#Message) dialogflow response is supported, just\r\n  * Text,\r\n  * Image\r\n  * Quick replies\r\n  * Cards (You see cards as texts, images, and buttons)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-dialogflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-dialogflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-dialogflow/lists"}