Function Calling

Warning: this feature is under active development and only working via API V2 => /api/v2/ChatMessage

Function calling allow Chatbot to send HTTP request to your web server to get specific data in order to answer customer's questions. To use this feature, you need:

1. Web server that can accept request from Chatbot.
2. Define JSON Schema Properties for Chatbot to understand how to send the request to your web server.

1. Web Server

Your web server need to accept either GET or POST request from Chatbot.

1. Accept GET Request: when Chatbot decide it makes sense to send a request to your server and your Webhook URL accept a GET request, it will replace value in curly brace in the URL before it make an HTTP request.

Original Webhook URL for GET Request:

https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}

For JSON Schema Properties:

{		
    "latitude": {		
        "type": "number",		
        "description": "Latitude of a location"		
    },		
    "longitude": {		
        "type": "number",		
        "description": "Longitude of a location"		
    }
}

Then whe user ask about the weather forcast for a location (eg: Redmond, WA), Chatbot will find the value of latitude and longitude and replace it in the URL to produce the following URL:

https://api.open-meteo.com/v1/forecast?latitude=47.674&longitude=-122.1217

This final Webhook URL will be used to get data from your web server in order to answer the user's questions.

2. Accept POST Request: when Chatbot decide it make sense to send a request to your server and your Webhook URL accept a POST request, it will look at your JSON Schema Properties for this Webhook URL and creat a JSON payload to send to your server. If you have a Webhook URL that accept POST request like this:

https://example.com/v1/forcast

And your have JSON Schema Properties like this:

{		
    "latitude": {		
        "type": "number",		
        "description": "Latitude of a location"		
    },		
    "longitude": {		
        "type": "number",		
        "description": "Longitude of a location"		
    }
}

Then whe user ask about the weather forcast for a location (eg: Redmond, WA), Chatbot will find the value of latitude and longitude and create a JSON payload like this to send to your web server:

{
    "latitude": 47.674,
    "longitude": 47.674
}

When your web server receive this JSON payload in the POST request and return data back to Chatbot, it will use that data to answer user's questions.

2. JSON Schema Properties

This JSON Schema Properties is inspired by ChatGPT JSON Schema when using function-calling directly on ChatGPT. On MybotChat, we want to make it simple for you, that mean you do not need to write the whole JSON Schema; you only need to write the Properties part of the schema. JSON Schema Properties is the valid JSON object that you define to help Chatbot understand what parameters your server need from Chatbot to return result.

Note: type in each property below must be valid JSON data type (string, number, integer, object, array, enum)

Example 1: A web crawler is accepting POST request to crawl a website by URL

{
    "url": {
        "type": "string",
        "description": "website url for crawler to crawl for content"
    }
}

Example 2: a hotel booking server is accepting a POST request to check for room availability within a date range

{
    "check-in-date": {
        "type": "string",
        "format": "date-time",
        "description": "date for a customer who want to book a room and check-in"
    },
    "check-out-date": {
        "type": "string",
        "format": "date-time",
        "description": "the date when a customer want to check-out of a hotel room"
    }
}

Example 3: a weather forcast that accept GET request to get weather information

{
    "latitude": {
        "type": "number",
        "description": "Latitude of a location"
    },
    "longitude": {
        "type": "number",
        "description": "Longitude of a location"
    }
}

Function-calling example 1: Weather forcast

In this example we are going to create a function calling for chatbot to get weather forcast information from open-meteo.com website using their free API.

1. From the Function Calling page of MybotChat, click "Add New" button to bring up the form and enter name: weather_forcast
2. For description enter: Get the current weather of a location by latitude and longitude
3. For Webhook Url enter:

https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m&hourly=temperature_2m&daily=sunrise,sunset&timezone=auto

Notice the two query strings: latitude= and longitude=

4. For HTTP Method select: GET
5. For JSON Schema Properties enter:

{
    "latitude": {
        "type": "number",
        "description": "Latitude of a location"
    },
    "longitude": {
        "type": "number",
        "description": "Longitude of a location"
    }
}

Notice the two JSON properties: latitude and longitude, it matches the two query string in Webhook URL.

6. No header security for this example because the API does not require any. If your server require header token, it can be set here.
7. From the Chatbot Console page ask the bot this question: tell me about the current weather in Redmond, WA
8. Chatbot is smart enough to know the value of the latitude and longitude of this location and make a web request to the Webhook address with valid location values. Behind the scene the Webhook URL is modified to this:

https://api.open-meteo.com/v1/forecast?latitude=47.674&longitude=-122.1217&current=temperature_2m&hourly=temperature_2m&daily=sunrise,sunset&timezone=auto

Now notice the two values in query strings: latitude=47.674 and longitude=-122.121

Here is the screenshot of the result in postman ui: