Botium Connector for Kore.ai Webhooks

This is a Botium connector for testing your Kore.ai 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 uses a Kore.ai Webhook channel to connect to your 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 Kore.ai chatbot with Webhook channel enabled
• a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Kore.ai Webhook Connector

When using Botium CLI:

> npm install -g botium-cli
> npm install -g botium-connector-koreai-webhook
> botium-cli init
> botium-cli run

When using Botium Bindings:

> npm install -g botium-bindings
> npm install -g botium-connector-koreai-webhook
> botium-bindings init mocha
> npm install && npm run mocha

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting your Kore.ai chatbot to Botium

You have to attach a Webhook channel to your Kore.ai chatbot:

1. Follow the instructions, use syncronous interation mode, and HS256 algorithm for JWT token.
2. From the Webhook configuration screen, copy those settings to the botium.json file:
   1. CLIENT ID
   2. CLIENT SECRET
   3. Webhook URL
3. Don't forget to publish the webhook

Open the file botium.json in your working directory and add the Webhook settings.

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "koreai-webhook",
      "KOREAI_WEBHOOK_URL": "https://bots.kore.ai/chatbot/hooks/...",
      "KOREAI_WEBHOOK_CLIENTID": "...",
      "KOREAI_WEBHOOK_CLIENTSECRET": "..."
    }
  }
}

Botium setup is ready, you can begin to write your BotiumScript files.

NLP Analitycs

• Extracting of NLP metadata has to be turned on (KOREAI_WEBHOOK_NLP_ANALYTICS_ENABLE). (It is not turned on as default, because it slows down the process.)
• The bot name has to set. (KOREAI_WEBHOOK_BOTNAME)
• The app associated with the Kore AI webhook has to have the Intent and Entity Detection scope.

Chatbot data downloader

• The app associated with the Kore AI webhook has to have the Utterances Export scope.

Chatbot data uploader

• The app associated with the Kore AI webhook has to have the Utterances Import scope.
• A new Kore AI Admin App is required (Kore AI Admin Console, Security & Control, API scopes )
• The Kore AI Admin App has to have the Bot Import scope
• The Kore AI Admin App has to be registered to Botium via KOREAI_WEBHOOK_ADMIN_CLIENTID, and OREAI_WEBHOOK_ADMIN_CLIENTSECRET.

Supported Capabilities

Set the capability CONTAINERMODE to koreai-webhook to activate this connector.

KOREAI_WEBHOOK_URL

The full Webhook URL from the Webhook configuration settings in V1 format:

• {{host_url}}/chatbot/hooks/{{bot id}} or
• {{host_url}}/chatbot/hooks/{{bot id}}/hookInstance/{{webHookId}}

KOREAI_WEBHOOK_CLIENTID

The CLIENT ID from the Webhook configuration settings

KOREAI_WEBHOOK_CLIENTSECRET

The CLIENT SECRET from the Webhook configuration settings

It is recommended to actually not add this to the botium.json file, but to use the environment variable BOTIUM_KOREAI_WEBHOOK_CLIENTSECRET instead

KOREAI_WEBHOOK_NLP_ANALYTICS_ENABLE

Turn it on to extract NLP metadata, like recognized intent, and entities.

KOREAI_WEBHOOK_NLP_ANALYTICS_URL

It is an advanced capability. In special cases it might be required to overwrite the URL calculated by Botium.

KOREAI_WEBHOOK_BOTNAME

The name of the Bot. If NLP Analytics is enabled, then this capability is required.

KOREAI_WEBHOOK_FROMID

If set, this userId will be used as sender. Otherwise, for each convo a new userId is generated.

KOREAI_WEBHOOK_TOID

If set, this userId will be used as receiver. Otherwise, for each convo a new userId is generated.

KOREAI_WEBHOOK_ADMIN_CLIENTID

The CLIENT ID of an app, created in Kore AI Admin Console

OREAI_WEBHOOK_ADMIN_CLIENTSECRET

The CLIENT SECRET of an app, created in Kore AI Admin Console

Open Issues and Restrictions

• Connector uses synch webhook API of Kore.ai. Always user has to start the conversation, and it is not possible to handle two following bot sections

Troubleshooting

• Error 412: The chatbot does not support anonymous access. Use KOREAI_WEBHOOK_FROMID capability, set the ID of a registered user.
• Error 401: The webhook is not available