Botium Connector for Genesys

This is a Botium connector for testing your Genesys chatbot.

Did you read the Botium in a Nutshell 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
• Botium Bindings
• Botium Box

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 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, 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": "[email protected]",
        "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 files.

How to start samples

There are some small demo in 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 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 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)

  • 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 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.

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.

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": "[email protected]",
    "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.