API sources

Kai API sources allow you to:

• Add user-specific context

• Execute functions (Upgrade plan, create an order, ...) when requested to

How does it work?

First of all you will need to specify a new function in Kai's data sources. Once specified, Kai automatically detects when to use the specified function. Example functions are:

• Get order details

• Get shipment status

• Create new subscription

• ...

Whenever Kai detects that a function should be used, Gleap will call the specified endpoint from you. Your endpoint will then need to respond with a JSON object containing a type ("context", "message") as well as either the context or message object.

When specifying a context, Gleap will pass the context to Kai, along with the general context, allowing Kai to answer the customers question.

When specifying a message, Gleap will directly reply with the specified message. This allows you to take full control on what to send back to the customer.

The cool part of Kai functions is, that you can also execute custom tasks on your backend, for example upgrade_plan could upgrade the user's plan. The possibilities are almost endless.

Add a new Kai function

To get started, navigate to AI Chatbot -> Content and then click "+ Add content". Now choose "API / functions". This will popup the Kai function editor.

The most important part is to name and describe your function.

Name:

only characters and "_" are allowed. It should be expressive like get_orders, get_order, get_customer_details...

Description:

Describe what the function does. Kai uses this to identify when to call the function. Examples are:

"Get order details for order with ID"

API url:

When your function gets called, Kai will do a HTTP-POST request to the URL specified here. You can also add custom request headers to add API tokens etc.

Function parameters

Function parameters allow you to specify parameters that get extracted from the customer's request. In our get_orders example, this could be an orderId for example. In other examples like get_hotels parameters could be something like location: string, filter_tags: string

Parameter name:

The name of the parameter: only characters and _ are allowed. This is also the key, that we use to send the parameter value with the POST request.

Parameter type:

Parameters can be of type string, boolean and number.

Description

The description allows Kai to better understand what to look for and how to format the parameter.

Enum values:

This is an optional field, that allows you to provide Kai with pre-defined values, which he needs to choose from. An example could be bug_priority with "LOW, MEDIUM, HIGH" as enum values.

Required:

If set, the parameter is required, otherwise it might be undefined.

How does the HTTP-POST request look like?

Whenever a Kai function gets executed, Gleap will perform a HTTP POST request to the specified request URL. The payload of this request looks like in the example below.

{
  "functionCall": "get_order",
  "params": {
    "order_id": 1234
  },
  "projectId": "PROJECT_ID_1",
  "session": {
    "gleapId": "GLEAP_ID_1",
    "email": "lukas@gleap.io",
    "userId": "1234",
    "value": 0,
    // ... other user data
  },
  "comments": [
    // previous comments in the conversation
  ],
  "ticket": {
    _id: ...,
    bugId: 12938,
    shareToken: "AHDHUEUHEUDAUSKDJAHSDKJAHSDKAJSHD",
    createdAt: ...,
    title: "Subject / ticket title",
    status: "OPEN",
    priority: "HIGH",
    type: "INQUIRY",
    formData: {
       key: "Value"
    },
    sentiment: "positive",
    isSpam: false,
    attachments: [...],
    metaData: {
       ...
    },
  }
}

functionCall:

This field contains the function name that got executed.

params:

This field contains all parameters that were identified, required for the function call.

projectId:

This is the Gleap project id.

session:

This object contains all user-specific informations like the userId, email, custom data, ... Especially the userId is important to fetch user-specific informations like orders, ...

comments:

This field contains the last 4 messages in the current conversation.

How to properly respond

There are two options on how to respond to a Kai function call.

Respond with context

For functions where you want to provide more information to answer the customers question, like "get_order_details", "get_subscription_info", ... you will want to respond as context. The response will be added to the context, that Kai uses to answer the customer's question.

{
"type": "context",
"context": "Order ID: #123\nStatus: Processed\nShipping status: In delivery\nPaid"
}

Answers must be of type application/json.

Context:

The provided context must be of type text. Provide as much information as needed, but as little as possible. The less overhead, the better.

Respond with documents

It's also possible to respond with documents, which will then be used by Kai to answer.

{
    "type": "documents",
    "documents": [
        {
            "title": "Invoice #1923",
            "url": "https://url-to-invoice.com/1923",
            "content": "Invoice has been paid. Total was 1920$. Line items: Item 1\nItem 2 ..."
        },
        {
            "title": "Invoice #9903",
            "url": "https://url-to-invoice.com/9903",
            "content": "Invoice is unpaid. Total was 199$. Line items: Item 1\nItem 2 ..."
        }
    ]
}

It's best practice to provide as much information as needed, but as less as possible.