Set up AI chatbot

Our AI chatbot is basically an AI Agent that uses your knowledge base as its source material.

Before you Enable AI chatbot widget for my knowledge base, use the Personalize the chatbot responses section to help refine your chatbot's tone and context:

1. Go to KB settings > AI chatbot. The AI chatbot page opens.
2. In the Personalize the chatbot responses section, follow the prompts to add context and personality to your chatbot:
   1. Enter a description of your chatbot's tone and personality in the Tone of voice field, max of 200 characters. This can determine how formal or informal, friendly or professional your chatbot's responses are. For example, for the chatbot in our Support KB, we use "friendly and helpful, uses occasional owl puns". 🦉
   2. Enter some context about your organization or audience in the Finish this sentence: "You are a chatbot answering questions for..." field, max of 200 characters. Include your organization's name and some information about its products or its intended audience. For example, for the chatbot in our Support KB, we use "KnowledgeOwl, a company that makes B2B knowledge base software."
3. Be sure to Save your changes.

You must opt in to use the AI chatbot in your knowledge base. To opt in:

1. Go to KB settings > AI chatbot. The AI chatbot settings page opens.
2. Be sure you've already followed the instructions to Personalize the chatbot responses.
3. Turn on the Enable AI chatbot widget for my knowledge base control.
4. Save your changes.

The AI chatbot will now appear in the lower right of all knowledge base pages!

When using the AI chatbot with private knowledge bases, or knowledge bases with a mix of public and private content, JWT authentication can be used to control access.

With JWT authentication, you'll need:

1. A JWT client secret to retrieve the token.
2. To update your chatbot embed script to pass in the JWT token to authenticate and display the chatbot to your readers.

Get your client secret

First,  generate the JWT Client Secret for your knowledge base:

1. Go to KB settings > AI Chatbot.
2. In the External website embed section, check the JWT authentication checkbox and click the Copy button. If no secret is displayed, click on the Generate JWT secret button to generate one.

Now that you have your client secret, go the the Embed code section and copy the JWT authentication embed code. The provided code includes 2 examples of how to use, choose the one that best fits your application workflow.

Working with JWT authentication

For information about what JWT is and how you can use it, refer to this JWT introduction article. For use with our contextual help widget, use the following requirements:

JWT header

Your JWT header must specify the HS256 encryption algorithm:

// Encryption algorithm must be HS256
{
  "alg": "HS256",
  "typ": "JWT"
}

JWT payload

Your JWT payload must include these fields and values:

{
  "iss": "https://app.knowledgeowl.com", // Issuer - *required
  "aud": "https://YOUR.KNOWLEDGEBASE.URL", // Audience - *required
  "service": "chatbot",
  "scope": "chatbot:interact",
  "iat" => unixTimestamp, // Issued At - *required
  "nbf" => unixTimestamp - 1000, // Not Before - *required
  "exp" => unixTimestamp + 1000, // Expires - *required
  "reader": {
    "ssoid": endUserUID, // Unique ID - *required,
    "username": endUserEmail, // Email or Username - *required,
    "groups": "Support,Admin" // Comma separated list of reader group names - optional
  }
}

When using the AI chatbot with private knowledge bases, or knowledge bases with a mix of public and private content, OAuth 2.0 authentication can be used to control access.

To use OAuth2, you'll need to generate a client ID and secret within KnowledgeOwl.

Generate Client Secret

To retrieve an OAuth2 token, you will first need to generate the Client Secret for your knowledge base:

1. Go to Settings > AI Chatbot.
2. In the External website embed section, check the OAuth 2.0 authentication checkbox. Copy both the Client ID and the Client secret and store them for use in your application. If there are no client ID and secret displayed, click on the Generate OAuth secret button to generate them.

Now that you have your client secret and client ID, you can use them to request an access token from the OAuth token endpoint. Now that you have your client ID and client secret, go the the Embed code section and copy the OAuth 2.0 authentication embed code. The provided code includes 2 examples of how to use, choose the one that best fits your application workflow. 

OAuth Request Token

/** CURL EXAMPLE **/
curl -u clientID:clientSecret https://app.knowledgeowl.com/oauth2/token
-d "grant_type=client_credentials&scope=chatbot:interact&reader[ssoid]=UID&reader[username]=reader@mysite.com&reader[groups]=Group1,Group2"

/** JS EXAMPLE **/
const clientID = 'yourClientID';
const clientSecret = 'yourClientSecret';
const credentials = btoa(`${clientID}:${clientSecret}`);

fetch('https://app.knowledgeowl.com/oauth2/token', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    scope: 'chatbot:interact',
    reader: {
      ssoid: 'UID',
      username: 'reader@mysite.com',
      groups: 'Group1,Group2'
    }
  })
})

Example Response

{
  "access_token":"1234567890987654321234567890987654321234",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope":"chatbot:interact"
}