API plugin

Create an API

1. Go to the chatbot workspace. Click Knowledge Base > API Plugin. Click Create API to open the Create API dialog box. Configure the API as follows:

• Service Name: Follow variable naming conventions. Use either snake_case, such as `income_proof`, or camelCase, such as `incomeProof`. Only English letters are allowed.

• Service Description: Describe the function of the API. You can include information about input and response parameters, such as "query weather based on location". You can also add special requirements. For example, "Parameters A and B are optional, but at least one must be specified."

• User prompt for long API calls: If an API call takes a long time, define a prompt message. For example, "Searching...".

• API Configuration: Configure the API call interface, headers, input parameters, response parameters, signature authentication, and service simulation.

  • Interface Configuration: Select the request method and enter the interface URL.

  • Header Parameters: Enter the request header parameters.

  • Input Parameters: For each parameter, specify the name, type, value source, whether it is required, and an explanation.

    • Parameter: This parameter must follow standard variable naming conventions and can contain only English characters.

    • Type: Includes String, Number, and Boolean.

      Note

      String: A text type used for names, descriptions, IDs, and status codes.

      Number: A numeric type that represents an integer or a floating-point number. Used for counts, amounts, and timestamps.

      Boolean: Represents true or false. Used for switches, statuses, and success flags.

    • Value Source: Includes model detection and passthrough parameters. Passthrough parameters are not sent to the model for detection.

    • Required: Specifies whether the parameter is required. An API should have at least one required parameter. The chatbot does not actively ask for optional parameters, but it detects them if the user provides the information.

    • Parameter Explanation: Similar to a parameter description. It includes a name, a format description, and an example.

    Note

    For other variable types, such as enumerations, the definitions are provided in the parameter descriptions. The following is an example of an input parameter definition:

    

  • Response Parameters: The specifications are the same as for input parameters.

    • First, determine the structure of the response parameters. The structure can be an Object, List, String, Number, or Boolean.

      Note

      Object: Structured data that consists of multiple fields.

      List: An ordered collection of elements of the same type. Each element can be a primitive data type or an object.

    • Mock Value: If you do not have a real request URL, use this field to set a fixed API response. You must also enable service simulation.

  • Signature Authentication: To ensure the secure use of HTTP/HTTPS services, enable signature calculation in the service configuration. When an API is called, the global service calculates a signature for services that have this feature enabled. The service then adds the signature to the request header.

  • For more information, see the Signature calculation guide.

  • Service Simulation: If you use a mock value for a response parameter, enable the service simulation switch.

    Note

    To use a mock value, enable the switch in the conversation debugging window. A mock value takes precedence over a URL request. For example:

2. After you finish the configuration, click OK to create the API. The following figure shows the interface after the API configuration is complete.

API debugging

After you configure the API plugin, use the Debug feature to verify that the chatbot can correctly call the API plugin.

1. Click the Debug button to open the API debugging window.

2. Enter the values for the input parameters and click Start Debugging. If the debug process is successful and returns the correct information, the interface is configured correctly.