This project provides an example of how to write a connector to communicate with a SAS Conversation Designer bot. This sample shows how a session is created and how events are used to interact with a bot.

This project is intended to only be a sample. Also, while this example is based on Node.js, the concepts of communicating with a bot are the same for other languages.

The following are required before using this project:

• A SAS Conversation Designer bot
• Node.js (at least version 12 recommended)

Clone this project locally and run:

npm install

Then update the following values in javascript/chat.js with values that match your environment:

• baseURL - this value points to the base url of your SAS environment (ex: if SAS Conversation Designer was deployed to http://yourcompany.com/SASConversationDesigner, then set this value to http://yourcompany.com)
• sasUserId - this is the user id that the connector will use to authenticate with your SAS environment
• sasPassword - the password for the userId defined above
• botId - this is the unique identifier for the bot you want the connector to communicate with (ex: e3b1f772-1562-4c8c-a60e-1ee20684ce4b)
• revisionId - this is the unique identifier for the bot revision within your bot that the connector will communicate with; this could be a delegate value (ex: @published, @latest) or the UUID (ex: aa1e4567-e89b-12d3-a456-426614158700)

Note: While userId and password are included above, the code can be changed to authenticate in other ways. More information about authentication can be found in the SAS REST APIs: Authentication & Authorization documentation.

Other values in javascript/chat.js that can be changed to better reflect your connector and the user using it:

• userId - the user id of the user interacting with the bot
• userName - the user name of the user interacting with the bot
• connectorName - the name of the connector displayed in the bot history view

To start the sample, run the following node command:

node sample-connector

Then in a browser, go to:

http://localhost:3000

We welcome your contributions! Please read CONTRIBUTING.md for details on how to submit contributions to this project.

This project is licensed under the Apache 2.0 License.

SAS Conversation Designer Documentation

The most common way to find the botId for a bot is using the Natural Language Conversations API (ex: if SAS Conversation Designer was deployed to http://yourcompany.com/SASConversationDesigner, then the base URL for the API would typically be http://yourcompany.com/naturaLanguageConversations). Once you have found the base URL, you can then call GET on the bots endpoint (ex: http://yourcompany.com/naturalLanguageConversations/bot). This will return a list of all bots that currently exist and you search the list for your bot. Once you find it the botId value is shown as 'id'.

Here is an example:

{
...
"items": [
  {
  "id": "7d3137bf-c306-4127-b513-3e3ab816d125",
  "createdBy": "sas",
  "creationTimeStamp": "2020-08-31T14:19:36.136Z",
  "modifiedBy": "sas",
  "modifiedTimeStamp": "2020-08-31T14:19:36.276Z",
  "name": "My bot",
  ...

The 'id' value (ex: 7d3137bf-c306-4127-b513-3e3ab816d125) should be used as the botId mentioned above.

There are three options for revisionId:

• @published - (recommended) this value points to the published version of your bot, then each time a new bot version is published, the connector automatically updates to use the most recently published bot version
• @latest - this value points to the latest/draft version of your bot, then each time a new bot latest/draft is created, the connector automatically updates to use the new latest/draft bot version
• specific revision id - this value points to a specific version the bot and will not change as versions are published or created

To find a specific revision id, follow the above instructions on how to get the botId. Then you can use the API to get access to all of the revisions available for a bot. This can be done by calling GET on the revisions endpoint (ex: http://yourcompany.com/naturalLanguageConversations/bot/{botId}/revisions). This will return a list of all revisions that currently exist for your bot. Then find the revision you are interested in and the revision value is shown as 'id'.

Here is an example:

{
...
"items": [
  {
  "id": "e09881bb-3206-4d73-a9c0-a6280202c188",
  "createdBy": "sas",
  "creationTimeStamp": "2020-08-31T14:19:36.136Z",
  "modifiedBy": "sas",
  "modifiedTimeStamp": "2020-08-31T14:19:36.276Z",
  "name": "My best revision",
  ...

The 'id' value (ex: e09881bb-3206-4d73-a9c0-a6280202c188) should be used as the botId mentioned above.