Integrate your chatbot with custom APIs

Using our AI actions editor you can build any custom integration with any backend system that can expose the data via API endpoints. For example you can make the chatbot to check the availability of the product in your warehouse, check the status of the order in your ERP system, or check the current balance on the customer account.

You can also execute actions to update external systems - for example call the endpoints that set appointments or Webhooks.

• Integrate your chatbot with custom APIs
• Prerequisites
• Adding a Custom API to Your Chatbot
• Your API
• API Invocation by the Chatbot
• Steps to set up Custom API
• Step 1: Navigate to the Custom API Settings
• Step 2: Define a New API
• Step 3: Add API Operations
• Step 4: Configure Endpoint URI and Parameters
• Step 5: Set the Request Method and Body
• Step 6: Set operation headers
• Step 7: Save the Operation
• Step 8: Test the API Integration
• Step 9: Attach the API operations to the chatbot
• Step 10: Add role instructions for the chatbot
• Tips for Successful Integration
• Securing Your Custom API Integration
• Use Constant Tokens
• Use login endpoint for temporary tokens
• Controlling Sensitive Information Through ChatLab
• Use Prompt Engineering to Guide the AI Behavior
• Design API Endpoints with Built-In Verification Logic
• Use Limited Data Scopes in API Responses

Prerequisites

Adding a Custom API to Your Chatbot

Integrating a custom API allows your chatbot to communicate with external services - for example your custom store, fetching data, or performing actions on behalf of the user.

This guide will walk you through the steps required to set up a custom API using the ChatLab platform.

Your API

You need to have publicly available API endpoints that can be called by the chatbot - this means you need to expose data from your e-commerce platform or your custom system via API endpoints so that our chatbot can call these endpoints in order to extract this data and provide it to your users.

API Invocation by the Chatbot

The API will be called dynamically by the chatbot during user interactions based on the chatbot's need to access external data or perform specific actions. It's important to note the following:

• No Guaranteed Invocation: The API will be invoked only when the chatbot's logic determines it is necessary. There are no guarantees on when or how often the API will be called.
• AI Model Requirements: For optimal performance, it is recommended to use higher-tier AI models that support complex function calling, such as GPT-4o or above. These models are more adept at determining the appropriate moments to invoke the API based on the context of the conversation and the user's intent.
• Context-Aware Calls: The chatbot will attempt to call the API whenever it identifies a context in the conversation that aligns with the API's purpose, but the actual call will depend on multiple factors, such as:
• Availability and response speed of the external API.
• The current state of the conversation and user prompts.
• Internal confidence levels and scoring algorithms of the AI model in deciding the necessity of the call.

Steps to set up Custom API

Step 1: Navigate to the Custom API Settings

1. Log in to your ChatLab dashboard.
2. In the left-hand sidebar, under the Settings section, click on Custom API.

Step 2: Define a New API

1. Click on the + Define API button.
2. Enter a name for your API in the API Name field.
3. Provide the base URL of the external service you want to connect to in the URL field.
4. Click Save to create the API.

Step 3: Add API Operations

1. In the newly created API entry, click on the View button.
2. Click on + Define API Operation to set up individual operations (endpoints) for the API.
3. Fill in the required details:
• Operation Name: A descriptive name for the operation.
• Operation URI: The endpoint path for the operation (e.g., /v1/resource).

Step 4: Configure Endpoint URI and Parameters

1. Endpoint URI Configuration:
• Add any path variables needed for the operation by clicking + Add path variable.
• Enter the variable details and mark them as required if necessary.

• Choose the value source:
• Provided by user to chatbot - in case some value from user is required to populate this.
• Constant - in case this is a constant value that you will need to provide at the moment of API operation definition
• add the newly added path variable into the path definition betwen two “@” signs: @myvariable@:

1. Query Parameters:
• Add any query parameters by clicking + Add query parameter.
• Define the parameter name, data type, and source (e.g., provided by user or chatbot).

Step 5: Set the Request Method and Body

1. Choose the HTTP method for the operation (e.g., GET, POST).
2. If the request method is POST, configure the request body:
• Choose the content type (e.g., application/json).
• Add the body parameters, specifying the name, data type, and source.

• Add the variables to the body definition - it usually is a json where you can place the variables that you have defined

Step 6: Set operation headers

Add headers - i.e Authorization or others needed by your API. Please take a look at the screenshot below for setting up permanent token in the Authorization header:

Step 7: Save the Operation

1. Review the configuration to ensure all details are correct.
2. Click Save changes to save the API operation.

Step 8: Test the API Integration

1. Use the Test API feature to send a test request and ensure that the integration is working correctly.
2. Monitor the logs for any errors or issues and adjust the configuration as needed.

Step 9: Attach the API operations to the chatbot

When you have the API Operations defined it is time to assign them to the chatbot. Select the chatbot in the main chatbots dashboard, click Integrations and select AI API Actions in the left menu

Click Attach on the selected API operation

Step 10: Add role instructions for the chatbot

Select your chatbot in the main chatbots dashboard, click Settings, in the left menu select Role

Click on Provide custom role instructions.

Add instructions on using newly added API operation for example you can add a rule:

“- When user asks for store inventory always call getItems function and render the result of the function with following rules…..”

Tips for Successful Integration

• Ensure that the base URL and endpoints are correct and accessible.
• Verify that any authentication requirements (like API keys or tokens) are configured properly.
• Test each operation thoroughly to ensure it returns the expected responses.

By following these steps, you can seamlessly integrate custom APIs into your ChatLab chatbot, enhancing its functionality and providing a richer user experience.

Securing Your Custom API Integration

To ensure that your custom API is secure and protected from unauthorized access, consider the following best practices:

Use Constant Tokens

Constant API Tokens: Set up a constant API token (or key) that is required for all requests to the API. This token should be unique and generated securely.

• How to Implement: Include the token in the request header or as a query parameter in every API call.
• Where to Store: Store the token securely in your ChatLab settings as the constant parameter of the operation

Use login endpoint for temporary tokens

Add additional API operation to the API that returns temporary security token - ie login endpoint to your system.

You will need to provide your login credentials matching your system as constant api operation parameters when defining this api operation. In order for the chatbot to be able to use the token obtained this way, you need to add security token in the definitions of other api operations and add proper prompt instructions to the login operation as well as to the other api operations (For example “Always use the security token obtained from the Login operation as the security_token parameter for operation getOrder”).

Controlling Sensitive Information Through ChatLab

To prevent sensitive information from being displayed by the chatbot, ChatLab users can take the following actions:

Use Prompt Engineering to Guide the AI Behavior

• Set Clear Instructions in Prompts: When configuring the chatbot, provide explicit instructions in the prompt settings to avoid displaying any sensitive information. For example:
• Prompt Example: "Do not display any personal, financial, or confidential information returned by an API call."
• Use of System Messages: Include a system message at the beginning of the conversation flow to reinforce the importance of data privacy (e.g., "Ensure all outputs exclude any sensitive information.").
• Regularly Update Prompts: Adjust the prompts based on user feedback or changes in data sensitivity requirements. This helps ensure the AI consistently follows the latest guidelines on handling sensitive information.

Design API Endpoints with Built-In Verification Logic

• Require User Verification for Sensitive Data Access: Design your API endpoints to include verification checks before returning sensitive data. For example:
• Verification Parameters: Require users to provide certain information (such as an email address, order number, or a specific security question) before the API returns data related to that user.
• Multi-Factor Verification: Implement additional parameters (e.g., order date, shipping address, or a secret code) to verify the user's identity and ensure they are authorized to access the data.
• Implement Fail-Safe Responses: Set your API logic to return generic messages or errors if the required verification is not provided or does not match:
• Example: "Unable to retrieve order details. Please verify your email and order number."

Use Limited Data Scopes in API Responses

• Minimize Data Exposure: Configure API responses to only include the necessary data for the chatbot's function, reducing the risk of inadvertently displaying sensitive information.
• Example: Instead of returning full user profiles, return only specific fields like order status or payment confirmation that are required for the chatbot's task.