BotCanvas Library

This library wraps the Bot Framework Web Chat React component. The BF-WC is a frontend chat client library that uses the Direct Line protocol to facilitate communication with a Bot Framework bot. Many of the parameters to the Bot Canvas component are simply passed to the BF-WC component and are thus documented in the BF-WC repo.

This library can be consumed by React applications, or by any other site by using an iframe of a page hosted in the OnlineEngine repository.

Useful Scripts

To run the example app and refresh on changes to the library:

BotCanvas> npm start
BotCanvas> cd example
BotCanvas\example> npm start

Install

npm install --save cci.botcanvas.library

Usage

import * as React from 'react'
import ChatApp from 'cci.botcanvas.library'

class Example extends React.Component {
  render () {
    return (
      <ChatApp
        cciProperties={{ cci_bot_id: "123456", cci_tenant_id: "654321" }}
        directLine={this.directlineFromToken} />
    )
  }
}

Parameters

| Name | Type | Optional | Usage | | --- | --- | --- | --- | | cciProperties | CCIProperties | no | customer's CCI bot ID and tenant ID | | directLine | DirectLine | no | created with a valid token and BotCanvas's exported createDirectLine function | | user | User | yes | controls the identifier of the user to the bot and the visible name of the user in the chat UI | | logMessage | (message: MessageData, error?: string) => void | yes | see Logging section below | | styleSet | StyleSet | yes | can customize the appearance of the chat, see BF-WC documentation for details | | attachmentMiddleware | Middleware | yes | can create custom cards in the chat UI, see BF-WC documentation for details | | middlewares | Middleware[] | yes | Redux middlewares that will be applied to the BF-WC store, see BF-WC documentation for details |

Types

• CCIProperties: information that the Bot Canvas automatically attaches to every outgoing message so the engine knows where to route the message | Property | Type | Optional | Usage | | --- | --- | --- | --- | | cci_tenant_id | string | no | the tenant in the CCI Bot Designer | | cci_bot_id | string | no | the id of the bot in the CCI Bot Designer | cci_content_version| string | yes | the specific version of the bot that this canvas should use |

• User: information about the user | Property | Type | Optional | Usage | | --- | --- | --- | --- | | id | string | no | a unique identifier for the user that associates them with their conversation state. if shared between two users (don't do this), their user state will be shared. if user object not created, a random ID will be generated for the conversation | | name | string | yes | a human-readable name that will be attached to every message sent by the user and available to the bot engine |

• MessageData: quality-of-service information about each message sent through the chat canvas | Property | Type | Optional | Usage | | --- | --- | --- | --- | | traceId | string | no | a unique-per-message ID generated by the bot and stored in the message channelData | | startTime | number | no | the time in milliseconds when the message was first sent (result of calling Date.now()) | | endTime | number | no | the time in miliseconds when the message was successfully sent or when an error happened (result of calling Date.now()) | | succeeded | boolean | no | whether the message was sent to the engine or if it failed to reach the engine -- note that a message reaching the engine does not guarantee that the bot engine handled it properly |

Logging

The Bot Canvas component relies on the parent app to handle the details of logging telemetry, but it allows for the provision of a logMessage function and invokes that function once per message. A logMessage implementation should take in a MessageData object, translate it into the logging schema specific to the parent app, and transmit the logging event to whatever telemetry service the parent app uses. If a logMessage parameter is not provided, the Bot Canvas repo will not track the success or failure of outgoing messages.

License

MIT ©