Web Component Tutorial

This guide will walk you through the steps necessary to implement Kallo convos within your own app. The steps will cover both back end and front end requirements.

We'll cover:

Step	Back or Front End
Integrating the convo web component	Front end
Creating a new convo	Back end
Generating an access token and JWT	Back end
Instantiating the convo in your app	Front end

Prerequisites

Before continuing, make sure you're prepared: Prerequisites

Steps

For this tutorial, let's assume the following:

The developer's Kallo user ID is bef7ca66-88f6-436a-a4f9-6713a5a2c42a
The API key for the developer's user is KkEeYy1234FfAaKkEe5678

1️⃣ HTML Page Setup

Import our package from the CDN by putting this script tag in the HTML head:

<head>
  <script src="https://storage.googleapis.com/kallo-cdn/components/convo/main.js"></script>
  ...
</head>

Then, place the kallo-sdk-convo tag in the body where the convo should be rendered:

<body>
<kallo-sdk-convo></kallo-sdk-convo>
...
</body>

Great! Now we've taken care of the minimum requirements to set up Kallo in your HTML page prior to obtaining access tokens from the API. We'll return to the HTML in a later step, after we've obtained an access token.

Optional: If you expect your users will be using and/or triggering responses that use KaTeX (mathematical statement rendering), follow these steps too:

1) Include a Document Type Declaration

Make sure your HTML files begin with:

<!DOCTYPE html>

2) Include KaTeX Libraries

Add these to the HTML head section:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.css"
      integrity="sha384-wcIxkf4k558AjM3Yz3BBFQUbk/zgIYC2R0QpeeYb+TwlBVMrlgLqwRjRtGZiK7ww" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.js"
        integrity="sha384-hIoBPJpTUs74ddyc4bFZSM1TVlQDA60VBbJS0oA934VSz82sBx1X7kSx2ATBDIyd"
        crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/contrib/auto-render.min.js"
        integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous"
        onload="renderMathInElement(document.body);"></script>

2️⃣ Create a Convo

In your back end code (or any REST client, if you're just trying things out), create a new convo in the Kallo API that we'll load into the web component.

For this example, we'll keep things simple: we'll create just a standard Kallo convo that doesn't belong to a Kallo topic and which has no special configuration. That means this convo will be owned by the user whose API key we're using to generate the access token.

API Request

curl -X POST https://api.kallo.ai/convos?userId=bef7ca66-88f6-436a-a4f9-6713a5a2c42a \
     -H "Authorization: Bearer api-key.KkEeYy1234FfAaKkEe5678" \
     -H "Content-Type: application/json" \
     -d '
        {
          "name": "New Convo 1717100397158"
        }
        '

Note that the userId query parameter is necessary to tell the API that this convo will be owned by the given user.

🧐 Other Owner Options

To create a convo owned by a team or a topic, refer to POST /convos in our OpenAPI spec.

API Response

{
  "id": "723752ed-8553-4756-9c3d-10a7ec77a83b",
  "name": "New Convo 1717100397158",
  "createdBy": "bef7ca66-88f6-436a-a4f9-6713a5a2c42a",
  "createdAt": "2024-05-29T20:19:57.379875383Z"
}

With this response, you'll need to take note of the convo id, which we'll need in the next step.

3️⃣ Generate an Access Token

Now we generate an access token to provide the end user with just enough access to the API—i.e. just enough to participate in the convo we just created.

API Request

curl -X POST https://api.kallo.ai/access-tokens \
     -H "Authorization: Bearer api-key.KkEeYy1234FfAaKkEe5678" \
     -H "Content-Type: application/json" \
     -d '
        {
          "userId": "bef7ca66-88f6-436a-a4f9-6713a5a2c42a",
          "scopeObjects": [
            {
              "id": "723752ed-8553-4756-9c3d-10a7ec77a83b",
              "type": "convo",
              "role": "participant"
            }
          ],
          "expiresAt": "2024-05-30T15:39:00Z"
        }
        '

API Response

{
  "id": "c3b80ad0-41c9-419c-9340-a1e20eeeba94",
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MTcwODM1NDAsImlhdCI6MTcxNzA4MzQ4NiwiaXNzIjoiYXBpLmthbGxvLmFpIiwianRpIjoiYzNiODBhZDAtNDFjOS00MTljLTkzNDAtYTFlMjBlZWViYTk0Iiwic2NvcGUiOiJjb252bzo3MjM3NTJlZC04NTUzLTQ3NTYtOWMzZC0xMGE3ZWM3N2E4M2IjcGFydGljaXBhbnQiLCJzdWIiOiJiZWY3Y2E2Ni04OGY2LTQzNmEtYTRmOS02NzEzYTVhMmM0MmEifQ.LndQAFKPae5SmCwsxvlylMHC-SbbLangBwGA_Be6kepZhEH5gfS3gZ04-d7bu-eNsdju7kB5S3T7g7R3YVYlUDZPQMai2bJmSbpIG7Z5gc77CXvNkk-wRhUWOIfiEnRh5FB9fVC06XteW1AqWnWT7qbhPID35NeNgPS5jQPX8zzXaIM67kEDHkq1HllKwgbWvLC3O-W7aiDgSIhuHvE86kYn3N0mUt1OttlZmuBEPv2nuTCLnAhb7v1BMTvL7OyH9_k9itrvW5VappdZjYXgoJWe8oO6CJZ-DcUg6CI-RD30SNBFjzINPvJT4bx5skJXmcrn_A1vNetTkCcYeX0geg"
}

We'll use the jwt value in the next step.

The id here should be retained if you wish to potentially revoke the access token prior to its expiration time.

4️⃣ Instantiate the Convo

Provide variables to set up the component:

<script>
  document.addEventListener('DOMContentLoaded', function () {
    const element = document.querySelector('kallo-sdk-convo');
    element.systemConfig = {
      accessToken: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MTcwODM1NDAsImlhdCI6MTcxNzA4MzQ4NiwiaXNzIjoiYXBpLmthbGxvLmFpIiwianRpIjoiYzNiODBhZDAtNDFjOS00MTljLTkzNDAtYTFlMjBlZWViYTk0Iiwic2NvcGUiOiJjb252bzo3MjM3NTJlZC04NTUzLTQ3NTYtOWMzZC0xMGE3ZWM3N2E4M2IjcGFydGljaXBhbnQiLCJzdWIiOiJiZWY3Y2E2Ni04OGY2LTQzNmEtYTRmOS02NzEzYTVhMmM0MmEifQ.LndQAFKPae5SmCwsxvlylMHC-SbbLangBwGA_Be6kepZhEH5gfS3gZ04-d7bu-eNsdju7kB5S3T7g7R3YVYlUDZPQMai2bJmSbpIG7Z5gc77CXvNkk-wRhUWOIfiEnRh5FB9fVC06XteW1AqWnWT7qbhPID35NeNgPS5jQPX8zzXaIM67kEDHkq1HllKwgbWvLC3O-W7aiDgSIhuHvE86kYn3N0mUt1OttlZmuBEPv2nuTCLnAhb7v1BMTvL7OyH9_k9itrvW5VappdZjYXgoJWe8oO6CJZ-DcUg6CI-RD30SNBFjzINPvJT4bx5skJXmcrn_A1vNetTkCcYeX0geg",
      userId: "bef7ca66-88f6-436a-a4f9-6713a5a2c42a",
      convoId: "723752ed-8553-4756-9c3d-10a7ec77a83b"
    }
  });
</script>

Setting the values in systemConfig is required.

Optionally, you can also set values in appearanceConfig to customize look and feel. Configuration options are discussed here.