# botium-connector-genesys

> Botium Connector for Genesys

Latest version **0.0.13** (published 2026-08-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install botium-connector-genesys
pnpm add botium-connector-genesys
yarn add botium-connector-genesys
bun add botium-connector-genesys
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.13 |
| Published | 2026-08-19 |
| First published | 2023-02-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 9 |
| Unpacked size | 631.3 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Botium GmbH |
| Maintainers | ftreml |

## Links

- npm: https://www.npmjs.com/package/botium-connector-genesys
- Homepage: https://www.botium.ai
- Issues: https://github.com/codeforequity-at/botium-core/issues
- npm.io page: https://npm.io/package/botium-connector-genesys

## Dependencies (9)

- [qs](https://npm.io/package/qs.md) ^6.11.0
- [ws](https://npm.io/package/ws.md) ^7.5.9
- [uuid](https://npm.io/package/uuid.md) ^7.0.3
- [debug](https://npm.io/package/debug.md) ^4.1.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [mime-types](https://npm.io/package/mime-types.md) ^2.1.35
- [randomatic](https://npm.io/package/randomatic.md) ^3.1.1
- [better-queue](https://npm.io/package/better-queue.md) ^3.8.12
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.6.2

## Recent versions

- 0.0.13 (latest) — 2026-08-19
- 0.0.12 — 2026-07-02
- 0.0.11 — 2026-06-11
- 0.0.10 — 2026-04-17
- 0.0.9 — 2025-10-29
- 0.0.8 — 2025-01-28
- 0.0.7 — 2024-04-22
- 0.0.6 — 2023-10-23
- 0.0.5 — 2023-10-02
- 0.0.4 — 2023-05-15
- 0.0.3 — 2023-04-17
- 0.0.2 — 2023-02-28
- 0.0.1 — 2023-02-28

## README

# Botium Connector for Genesys

[![NPM](https://nodei.co/npm/botium-connector-genesys.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/botium-connector-genesys/)

[![Codeship Status for codeforequity-at/botium-connector-genesys](https://app.codeship.com/projects/ac5ab3a0-d0f5-0138-cac3-16239a5027f5/status?branch=master)](https://app.codeship.com/projects/408148)
[![npm version](https://badge.fury.io/js/botium-connector-genesys.svg)](https://badge.fury.io/js/botium-connector-genesys)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg)]()


This is a [Botium](https://github.com/codeforequity-at/botium-core) connector for testing your [Genesys chatbot](https://www.genesys.com/genesys-cloud).

__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!__

## How it works
Botium connects to the API of your Genesys chatbot.

It can be used as any other Botium connector with all Botium Stack components:
* [Botium CLI](https://github.com/codeforequity-at/botium-cli/)
* [Botium Bindings](https://github.com/codeforequity-at/botium-bindings/)
* [Botium Box](https://www.botium.at)

## Requirements
* **Node.js and NPM**
* a **Genesys bot flow**
* a **project directory** on your workstation to hold test cases and Botium configuration

## Install Botium and Genesys Connector

When using __Botium CLI__:

```
> npm install -g botium-cli
> npm install -g botium-connector-genesys
> botium-cli init
> botium-cli run
```

When using __Botium Bindings__:

```
> npm install -g botium-bindings
> npm install -g botium-connector-genesys
> botium-bindings init mocha
> npm install && npm run mocha
```

When using __Botium Box__:

_Already integrated into Botium Box, no setup required_

## Connecting Genesys chatbot to Botium

You can choose between Web messaging and Open messaging channels based on `GENESYS_MESSAGING_CHANNEL` (WEB_MESSAGING, OPEN_MESSAGING) capability.  

### Use web messaging channel (websocket) - Recommended

If you set 'WEB_MESSAGING' value in `GENESYS_MESSAGING_CHANNEL`, then you choose Web messaging channel, which is a websocket based channel.

In Genesys cloud you have to do the following:
* You have to have a `Digital Bot Flow` or a `Bot Flow`, which is connected to an `Inbound Message Flow` under Architect page
* You have to set up a `Messenger Configuration` under Admin page 
* You have to create a `Messenger Deployment` under Admin page

After the `Messenger Deployment` you create a `botium.json` file and copy the Deployment Key into `GENESYS_DEPLOYMENT_ID` 
and set your genesys account AWS region into `GENESYS_AWS_REGION`.

```
{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "genesys",
      "GENESYS_MESSAGING_CHANNEL": "WEB_MESSAGING",
      "GENESYS_AWS_REGION": "us-east-1",
      "GENESYS_DEPLOYMENT_ID": "baf4d3ab-d758-4439-995e-c4d86f6d9121"
    }
  }
}
```
To check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:

```
> botium-cli emulator
```

Botium setup is ready, you can begin to write your [BotiumScript](https://botium.atlassian.net/wiki/spaces/BOTIUM/pages/491664/Botium+Scripting+-+BotiumScript) files.

### Use open messaging channel (webhook)

If you set 'OPEN_MESSAGING' value in `GENESYS_MESSAGING_CHANNEL`, then you choose Open messaging channel, which is a webhook based channel.

In Genesys cloud you have to do the following:
* You have to have a `Digital Bot Flow` or a `Bot Flow`, which is connected to an `Inbound Message Flow` under Architect page
* Under `Admin/Message/Platform` menu you have to create a new integration for  `Open Messaging`. You have to add here a webhook URL which is the endpoint to your botium box instance or to `botium-cli inbound-proxy`. (from localhost you can use [ngrok](https://ngrok.com/), see later)
* Under `Admin/Routing/Message` Routing you have to add a new Message route. Select here your `Inbound Message Flow` and add in addresses your `Open Messaging` integration.
* Under `Admin/Integrations/OAuth` create OAuth client credentials with the corresponding roles

After you finished the steps in Genesys you can create a `botium.json` file. (The value for `GENESYS_OPEN_MESSAGING_INTEGRATION_ID` you can find in the url when you open in genesys cloud your open messaging integration for edit)

```
{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "genesys",
      "GENESYS_MESSAGING_CHANNEL": "OPEN_MESSAGING",
      "GENESYS_AWS_REGION": "us-east-1",
      "GENESYS_CLIENT_ID": "5305cdc8-5ef9-49b9-8cbe-95e87bd3c123",
      "GENESYS_CLIENT_SECRET": "vL9kEoHLCb6AWmby5xpHrbAKviL-Lzu6WCiBUZTt123",
      "GENESYS_OPEN_MESSAGING_INTEGRATION_ID": "1387d005-b09a-4788-bf53-16c378cdc111",
      "GENESYS_USER_DATA": {
        "nickname": "Messaging User",
        "id": "messaging-user@externalservice.com",
        "idType": "email",
        "firstName": "Messaging",
        "lastName": "User"
      },
      "SIMPLEREST_INBOUND_REDISURL": "redis://127.0.0.1:6379"
    }
  }
}
```

To check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:

```
> botium-cli emulator
```

Botium setup is ready, you can begin to write your [BotiumScript](https://botium.atlassian.net/wiki/spaces/BOTIUM/pages/491664/Botium+Scripting+-+BotiumScript) files.

## How to start samples

There are some small demo in [samples](./samples) with Botium Bindings.
By changing the corresponding capabilities you can use it with your Genesys bot.

### Genesys web messaging sample

* Install the dependencies and botium-core as peerDependency:
    ```
    > npm install && npm install --no-save botium-core
    ```
* Navigate into the [web messaging sample](./samples/webmessaging) directory
    * Install the dependencies
        ```
        > cd ./samples/webmessaging
        > npm install
        ```
    * Adapt botium.json in the sample directory:
        * Change `GENESYS_AWS_REGION` with your Genesys aws region
        * Change `GENESYS_DEPLOYMENT_ID` with your Messenger Deployment key
        * Change `GENESYS_CUSTOM_ATTRIBUTES` if necessary
    * Finally run the test
        ```
          > npm test
        ```

### Genesys open messaging sample   


* Navigate into the [web messaging sample](./samples/openmessaging) directory
    * Install the dependencies
        ```
        > cd ./samples/openmessaging
        > npm install
        ```
    * Adapt botium.json in the sample directory:
        * Change `GENESYS_AWS_REGION` with your Genesys aws region
        * Change `GENESYS_CLIENT_ID` with your OAuth Client Id
        * Change `GENESYS_CLIENT_SECRET` with your OAuth Client Secret
        * Change `GENESYS_OPEN_MESSAGING_INTEGRATION_ID` with your Open Messaging integration Id
        * Change `GENESYS_USER_DATA` if necessary
        * Change `GENESYS_CUSTOM_ATTRIBUTES` if necessary

    * Start `inbound-proxy` (it will listen on `http://127.0.0.1:45100/`):
      ```
        > npm run inbound
      ```
        * In your open messaging integration in Genesys cloud you need to set `
          SzabiTest
          Outbound Notification Webhook URL` according to the previous step set up inbound-proxy url.
          (To make this localhost url public you can use e.g. [ngrok](https://ngrok.com/))
    * Finally run the test
        ```
          > npm test
        ```

## Supported Capabilities

Set the capability __CONTAINERMODE__ to __genesys__ to activate this connector.

#### GENESYS_AWS_REGION*
You have to specify the AWS region where your Genesys account located

#### GENESYS_MESSAGING_CHANNEL*
You can choose between Web Messaging (WEB_MESSAGING) - websocket and Open Messaging (OPEN_MESSAGING) - webhook channels

#### GENESYS_NLP_ANALYTICS
You can enable NLP analytics by this boolean flag. (false by default)

### Genesys OAuth permissions for NLP analytics and NLP only mode

For `GENESYS_NLP_ANALYTICS` and NLP only mode the connector uses the Genesys Cloud Platform API to read the Architect flow configuration and to call the NLU/Knowledge APIs. In Genesys, add the following permissions to the role assigned to the OAuth client credentials. Genesys also requires matching OAuth scopes; the read-only scopes are enough for these calls.

Minimum permissions for intent detection without a Genesys Knowledge Base:

| Endpoint used by the connector | Required permission | OAuth scope |
| --- | --- | --- |
| `GET /api/v2/flows` | `architect:flow:view` | `architect:readonly` |
| `GET /api/v2/flows/{flowId}/latestconfiguration` | `architect:flow:view` | `architect:readonly` |
| `POST /api/v2/languageunderstanding/domains/{domainId}/versions/{domainVersionId}/detect` | one of `languageUnderstanding:nluDomainVersion:view` or `dialog:botVersion:view` | one of `language-understanding:readonly` or `dialog:readonly` |

The intent import handler, and intent detection with `GENESYS_LANGUAGE` set, additionally read the NLU domain version, so they use the same NLU permission and scope for:

| Endpoint used by the connector | Required permission | OAuth scope |
| --- | --- | --- |
| `GET /api/v2/languageunderstanding/domains/{domainId}/versions/{domainVersionId}` | one of `languageUnderstanding:nluDomainVersion:view` or `dialog:botVersion:view` | one of `language-understanding:readonly` or `dialog:readonly` |

If the bot flow is configured with a Genesys Knowledge Base, add these permissions as well:

| Endpoint used by the connector | Required permission | OAuth scope |
| --- | --- | --- |
| `POST /api/v2/knowledge/knowledgebases/{knowledgeBaseId}/documents/search` | `knowledge:knowledgebase:search` | `knowledge:readonly` |
| `GET /api/v2/knowledge/knowledgebases/{knowledgeBaseId}/documents` | `knowledge:document:view` | `knowledge:readonly` |

When `detectNlpData` is called with a Genesys message id and `GENESYS_BOT_FLOW_ATTRIBUTE_NAME`, the connector also reads the message and conversation to select the matching bot flow. Add these permissions only for that setup:

| Endpoint used by the connector | Required permission | OAuth scope |
| --- | --- | --- |
| `GET /api/v2/conversations/messages/{messageId}/details` | one of `conversation:message:view` or `conversation:webmessaging:view` | `conversations:readonly` |
| `GET /api/v2/conversations/{conversationId}` | `conversation:communication:view` | `conversations:readonly` |

You can verify the current permission and scope requirements in the [Genesys Cloud API Explorer](https://developer.genesys.cloud/devapps/api-explorer) by opening each endpoint and checking the "Required Permissions" section.

#### GENESYS_INBOUND_MESSAGE_FLOW_NAME
When you turn on `GENESYS_NLP_ANALYTICS`, then it's required to specify the inbound message flow name.

#### GENESYS_LANGUAGE
The language used for intent detection and for the conversation model downloader, in `en-us` format. 
When it is not set, the default language of the bot flow is used.

Only set this for a multilanguage bot flow, see [Multilanguage bot flows](#multilanguage-bot-flows).

#### GENESYS_LANGUAGE_ATTRIBUTE_NAME
The custom attribute the language is sent in, `language` by default. Set it to an empty string to not 
send the language at all.

Genesys maps custom attributes to participant data, so an Architect flow can read this attribute and 
switch the language of the conversation. See [Multilanguage bot flows](#multilanguage-bot-flows).

The attribute is sent with every message, also when `GENESYS_LANGUAGE` is not set, in which case it 
falls back to `en-us`. This is on purpose: a `Set Language` action in an Architect flow fails when the 
participant data it reads is missing, and the flow then answers nothing at all.

### Multilanguage bot flows

A Genesys bot flow has one default language, chosen when the bot flow is created, and optionally 
further supported languages. Intent names are shared between all languages, only the training 
utterances are localized. In the API this is one NLU domain with a separate NLU domain version per 
language.

Set `GENESYS_LANGUAGE` to the language you want to test, for example `es-es`. The connector then

* detects intents in the NLU domain version of that language, instead of the default one
* downloads the utterances of that language in the conversation model downloader
* sends the language as custom attribute, see below

Use one Botium chatbot, or at least one test set, per language. Since intent names are shared between 
languages while the utterances are not, a test set mixing languages sends utterances to the model of 
another language, which fails by design.

#### Switching the language of the conversation

`GENESYS_LANGUAGE` selects the language Botium analyses the conversation in. It does not switch the 
language the bot answers in, because Genesys has no API for that. To get answers in the requested 
language, the Architect flow has to read the custom attribute the connector sends and switch the 
language itself:

* Add a `Get Participant Data` action which reads the `language` attribute into a flow variable
* Add a `Set Language` action which uses that variable as expression
* Add the language under `Supported Languages` of every bot flow involved, with trained utterances

The connector always sends the attribute, `en-us` when `GENESYS_LANGUAGE` is not set, so the flow 
never has to deal with a missing value. If your bot answers in another language by default, set 
`GENESYS_LANGUAGE` accordingly, or set `GENESYS_LANGUAGE_ATTRIBUTE_NAME` to an empty string to leave 
the language of the conversation entirely to the flow.

Without these steps the bot keeps answering in its default language, while Botium still reports the 
intents of the requested language. In that case the NLP analytics of a web messaging or open 
messaging test do not match what the bot actually did. `NLP_ONLY` mode is not affected, it only uses 
the NLU API.

#### Knowledge base limitation

The Genesys knowledge API cannot be queried by language. When `GENESYS_LANGUAGE` differs from the 
default language of the bot flow, the connector therefore skips the knowledge base of that bot flow, 
both for intent detection and for the conversation model downloader, and only uses the NLU domain.

### WEB MESSAGING

#### GENESYS_DEPLOYMENT_ID*
You have to set the Messenger Deployment key here

### OPEN MESSAGING

#### GENESYS_CLIENT_ID*
Genesys OAuth Client Id

#### GENESYS_CLIENT_SECRET*
Genesys OAuth Client Secret

#### GENESYS_OPEN_MESSAGING_INTEGRATION_ID*
Open Messaging integration Id (you can find it in the browser url)

#### GENESYS_USER_DATA
You can define a user data object.
E.g.:
```
{
    "nickname": "Messaging User",
    "id": "messaging-user02@externalservice.com",
    "idType": "email",
    "firstName": "Messaging",
    "lastName": "User"
}
```

#### GENESYS_CUSTOM_ATTRIBUTES
You can define a custom attribute object.
E.g.:
```
{
    "department": "sales",
    "device": "mobile"
}
```

The connector adds the language to these attributes under the name configured in 
`GENESYS_LANGUAGE_ATTRIBUTE_NAME`, using `GENESYS_LANGUAGE` or `en-us`. An attribute defined here 
explicitly is never overwritten.

---
_Source: https://npm.io/package/botium-connector-genesys · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._