Skip to main content

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.

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.

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

`Functions modal settings.`

DB Function specific configuration

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

`Functions modal settings.`

HTML Function specific configuration

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

`Functions modal settings.`

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)

`Functions Chat modal settings.`

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.

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.

`Agent modal settings for functions.`

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, '*')