Functions

Functions allow an AI instance (or agents) to consume data from an API endpoint. Administrators can apply settings to functions which determine how an agent makes requests to an API.

Menu location

Functions can be created and or edited from the following menu: Settings > Functions

Types of Function

There are three different types of functions available for creation to the user, which are

1. API (Calls to retrieve information from an api)
2. DB (Actions performed on an SQL database called)
3. HTML (Embedding of html elements into the chat called)
4. CHAT (Chatbot to user communication)

Functions of these types can be created by specifically clicking the associated function type in the menu location. Note however that HTML functions are available only from Pro plan onwards and DB functions are available only for Enterprise plans.

Configuring Functions

The required details for creating a function are:

• Name
• Description
• Callback

When configuring the setting Description it is especially important to clearly state the specific purpose of the function, because the chat agent is basing its decision to invoke a function on this field. We recommend to include as much detail as possible in this field try to stay short and concise.

Regarding the callback setting, when it is Off the function will be called upon the user asking a question, while when it is On the function will be called upon the agent answering the question. This allows the user to have more control over when the function is called. For example if the function needs to log the user's details, it is better to have the callback setting set to On so that the function is called after the agent has answered the question. While insted if the function needs to retrieve some information from an external source, it is better to have the callback setting set to Off so that the function is called before the agent answers the question.

Hand-off

The hand-off setting is available to allow the user to pass the conversation to another chat agent. This is useful when the workspace has multiple agents with multiple skills and the user needs to be transferred to another agent to answer a specific question. A common flow for this setting can be seen below:

1. Receptionist agent is created to answer general questions with very limited access to the customer database (e.g. the agent can only answer questions about the company's products and services or retrieve customer and case id based on the information provided by users in the chat). In oher words the agent is not able to retrieve any information from the customer database aside from the customer or the case id.
2. Customer service officer agent is created to answer questions with access to the customer database - therefore it can retrieve personal information about the customer and the case.
   1. The agent is assigned to a function which allows the agent to consume an API to retrieve information from the customer database to match name and phone number or order id to the customer ID.
   2. The information required to retrieve customer and case information is completely unopinionated and it can be easily customised to meet any verification requirement.
      1. For the function to persist the customer and the case information, the function must have Customer authentication or Case authentication set as scope.
   3. Regardless of the information required, the function must have the Agent hand-off enabled by selecting the agent Customer service officer to hand-off to.
3. A customer makes an inquiry about their order status providing the order number or their name and phone number.
4. The Receptionist agent will consume the API to retrieve the customer ID and case ID. The agent will then hand-off the conversation to the Customer service officer agent which has access to the customer database.
5. Moving forward the Customer service officer agent will be able to provide the customer with the information they require.

The hand-off setting allows an agent to handing off the conversation with multiple agents in the workspace depending on the interaction with the users in the chat. As it is part of the function settings, the hand-off can be chained with multiple agents in the workspace. Simple chain Agent A > Agent B > Agent C > Agent D Complex chain Agent A > [Agent B > Agent C] > Agent D

danger

The agent hand-off poses a security risk if the function is not correctly configured. It is important to ensure that the function is correctly configured to prevent any data leakage as, due to the hand-off, data will be passed to another agent that should not have access to the information accessible by the initial agent.

API Function specific configuration

• URL (The endpoint of the API for the associated Agent to consume)
• Parameters (These are the required fields to consume the API)
• Request Type

DB Function specific configuration

• Stored procedure (procedure of the db that is to be executed)
• Connection type (type of SQL database)

HTML Function specific configuration

• URL (url of the html that is to be included)
• Message on successful submit
• Message on failed submit

Chat Function specific configuration

• Chat script (script of the chatbot that is to be included)
• Chat action (whether the chatbot should suggest a different question or indicate the next step of the conversation)

Parameter settings (API only and DB functions)

When creating a function, by default a code block is provided which demonstrates the required settings needed to consume the API URL. The properties object is required and must include the parameters which the API needs to make requests. The code block which is provided by default when creating a function is below:

{
"type": "object",
    "properties": {
        "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
        },
        "unit": {
            "type": "string",
            "enum": ["celsius","fahrenheit"]
        }
    },
    "required": ["location"]
}

For each object within the properties object, a key (or property) which relates to the API's parameters needs to be included. In the example code block above, location is a required paramter for consuming the API. Within each property is a type which must be included. A type is the data type which is used by this parameter eg ("string", "number", "array", "object" types).

These properties (or parameter objects) should also contain a description key with details about what the property is. The more descriptive and accurate the description, the better the results an agent can provide. The agent will use these description items as a reference for how to answer questions and consume the API.

The required array is used to list out the mandatory properties needed for making requests.

Scope (API only and DB functions)

Scope is extremely useful when the function is required to persist data for the duration of the conversation and especially when the agents need to authenticate the customer or the case prior to disclosing any sensistive information. ToothFairyAI abstracts the two key components of such interactions in the chat with the concept of Customer and Case. This allows complex service interactions or internal workflows to be handled by the agent without overloading the agent with unnecessary information. The scope setting allows the user to define what kind of the data is being persisted within the chat session for any given agent and function.

The available options are Customer retrieval, Case retrieval, Customer authentication, and Case authentication.

• Customer retrieval - This scope is used to persist data related to the customer for the duration of the conversation. The data is stored in the customerInfo object and can be accessed by the agent throughout the conversation. To take effect, the function must have the customer id populated manually at the creation of the chat or a Customer authentication function must be accessible by the agent to store the customer id at runtime based on the information provided by the user in the conversation.
• Case retrieval - This scope is used to persist data related to the case for the duration of the conversation. The data is stored in the caseInfo object and can be accessed by the agent throughout the conversation. To take effect, the function must have the case id populated manually at the creation of the chat or a Case authentication function by the agent to store the case id at runtime based on the information provided by the user in the conversation.
• Customer authentication - This scope is used to persist only the customer id within the session (use JSON path extractor to correcly setup this workflow when the response is a JSON object). The data is stored in the customerId field and can be used by any agent with a function with Customer retrieval as scope to retrieve the customer information.
• Case authentication - This scope is used to persist only the case id within the session (use JSON path extractor to correcly setup this workflow when the response is a JSON object). The data is stored in the caseId field and can be used by any agent with a function with Case retrieval as scope to retrieve the case information.

It is recommended to couple the scope setting with the Agent hand-off feature to implement additional information segregation with unauthenticated customer/case.

Thanks to these settings virtually any customer/employee interaction can be handled by the agent with focus on a customer and/or a case (quotation, ticket, meeting etc).

JSON path extractor

The JSON path extractor is an optional setting which allows the user to extract specific data from the API response. The JSON path extractor is used to extract data from the API and DB stored procedure response at a specific path. For example if the API response is:

{
  "customer": {
    "name": "John",
    "tickets": [
      {
        "id": 1,
        "status": "open"
      },
      {
        "id": 2,
        "status": "closed"
      }
    ]
  }
}

And we are only interested in the id of the first ticket, the JSON path extractor would be customer.tickets.0.id.

Request type (API only)

The available requests options for the request type is limited to GET and POST. This was a deliberate deciscion applied for security reasons. No PUT, PATCH or DELETE requests are included but can be made available by contacting ToothFairyAI support.

Authorisation type (API only)

This optional setting is available to authenticate the request if it is required. API keys, OAuth2 credentials, and Bearer tokens must be set in the authorisations section of the function settings. Once an authorisation is created, select the authorisation type using the dropdown menu. After an authorisation type is selected, the Authorisation dropdown will appear allowing the user to select the authorisation created.

Additional headers (API only)

This optional setting is available to provide additional headers when making requests if it is required.

Static arguments (API only)

This optional setting is available to allow constant settings for the predefined properties when the agent consumes the API. For example, if a property is the same for all requests (eg a userID), then adding those details in this area will ensure that this property is always set to the same value.

Agent settings for Functions

An agent needs to be created in order to assign a function to it. One agent can be assigned to multiple functions of multiple types.

In general, a Topic needs to be defined and assigned to an agent as well to ensure that the agent can answer questions. The Topic is a collection of documents that the agent can use to answer questions. The Topic is assigned to the agent in the Knowledge Settings section of the agent settings.

Passing information from HTML functions to ToothFairyAI

Information from a displayed HTML element in the chat can be passed back to ToothFairy's AI agent via window.top.postMessage. The data that gets send to ToothFairy needs to be a JSON object where all elements to be sent are given as a value in JSON object form to the key "data". To ensure that ToothFairy knows that the data is coming from an HTML element, the key "tf_event_type" needs to be set to "form_submit". An example of how this can be done is shown below:

var message_form = {
            "data":{
                "name":name,
                "surname":surname,
                "driving_license":drivingLicense
            },
"tf_event_type" : "form_submit"
        }
window.top.postMessage(message_form, '*')