API Connections

Connect your chatbot to external APIs to fetch or send data, enabling complex interactions and providing users with dynamic information.

Connection Basics

An API Connection defines how your chatbot interacts with a specific external API endpoint. These are the core details you{'''}ll configure:

Connection Name

Assign a clear, descriptive name (e.g., "Get User Orders","Weather API"). This helps both you and the AI identify the connection's purpose.

Description for AI

Crucial for functionality. Provide detailed instructions for the AI on when and how to use this API. Explain the API's purpose and the specific types of user requests or conversational contexts that should trigger its use.

Example: "Use this API to fetch order details when a user asks about the status of a specific order. Requires an order ID."

HTTP Method

Select the HTTP method (GET, POST, PUT, DELETE, PATCH) that the external API endpoint expects for this specific action.

Endpoint URL

Enter the full URL of the API endpoint (e.g., https://api.example.com/v1/users/{userId}/orders).

Path Parameters

If your URL contains placeholders enclosed in curly braces (like {userId} above), these will be automatically detected as Path Parameters.

You will configure how the AI obtains values for these path parameters in a separate section below the main parameters. Unlike Query or Body parameters, Path Parameters are defined by the URL structure and cannot be manually added or changed to a different type ('Send In').

Authentication

Configure how your chatbot authenticates with the API. Your credentials are stored securely.

  • No Authentication: For APIs that don't require authentication.
  • API Key: Provide the Header Name (e.g., X-API-Key) and the Key Value.
  • Bearer Token: Provide the Token value.
  • Basic Auth: Provide the Username and Password.

Enable Connection

Toggle this switch to activate or deactivate the connection. Disabled connections won't be used by the AI.


Configuring Parameters

Parameters are the data sent along with your API request. There are two main types: Manually Added Parameters (sent in the Query String or Request Body) and Detected Path Parameters (part of the URL).

Manually Added Parameters (Query & Body)

Use the "Add Manual Parameter" button to define data sent as Query Parameters or within the Request Body.

Parameter Name

The exact name the API expects (e.g., searchQuery, product_id). Must contain only letters, numbers, and underscores.

Send In

Choose how this parameter is sent:

  • Query Parameter: Appended to the URL's query string (e.g., ?limit=10&offset=20). Typically used with GET requests.
  • Request Body (JSON): Included in the JSON payload of the request body. Typically used with POST, PUT, PATCH requests.

Parameter Source

Define where the chatbot gets the value for this parameter:

  • Extract from Conversation: The AI attempts to extract the value dynamically from the user's conversation based on your instructions.
    Description for AI (Required for Extract):

    Provide clear instructions for the AI (e.g., "Extract the city name mentioned by the user for the weather lookup", "Find the 8-digit tracking number from the user's message").

  • From Provided Context (JS API): The value is automatically retrieved from the user context object provided via the website integration (JS API).
    Context Key Name (Required for Context):

    Specify the exact key from your context object (e.g., userId, userEmail). Must contain only letters, numbers, and underscores.

Required Parameter

Toggle whether this parameter is essential for the API call. If required and the value cannot be obtained, the API call may fail or be skipped.

Detected Path Parameters

If your Endpoint URL includes placeholders like {placeholder}, they appear here automatically. You only need to configure their Source (how the AI gets the value).

Parameter Name

Automatically determined from the URL placeholder (e.g., userId if the URL contains {userId}). This cannot be changed here.

Send In

Always
Path Parameter
. This indicates the value replaces the corresponding placeholder in the URL path and cannot be changed.

Parameter Source

Define where the chatbot gets the value for this path segment. The options are the same as for manual parameters:

  • Extract from Conversation: Requires a Description for AI explaining what value to extract from the conversation for this URL segment.
  • From Provided Context (JS API): Requires a Context Key Name to pull the value from the provided user context.

Required Parameter

Toggle whether this path parameter is essential. If required and the value cannot be obtained, the API call will likely fail.


Managing Connections & Parameters

After creation, API Connections are listed in the dashboard. You can edit the connection details, view configured parameters, and manage them.

  • Editing Connections: Click the edit icon on a connection to modify its basic details, authentication, or enabled status.
  • Viewing Parameters: Parameters (both manual and path) are displayed within each connection's details, showing their name, send-in type, source, and requirement status.
  • Deleting Manual Parameters: Manually added Query and Body parameters can be deleted using the trash icon.
  • Path Parameters: Path parameters are tied to the Endpoint URL. They cannot be deleted directly or changed ('Send In'). To remove or change a path parameter, you must modify the Endpoint URL itself in the connection settings. You can, however, edit their Source configuration (how the AI gets the value).

Setting User Context for API Calls

When you configure API parameters with the source From Provided Context (JS API), you need to provide the user context data through your website integration. This allows your API calls to use personal data like user IDs, email addresses, subscription status, or any other user-specific information.

How Context Works

The chatbot exposes a window.easyfindai.setContext() function that accepts a single argument: a JavaScript object (\`userData\`). This object can contain any key-value pairs you need, as long as it can be serialized to JSON.

When you configure an API parameter with the source "From Provided Context (JS API)", you must specify a "Context Key Name". The system will then look for a key inside the \`userData\` object you provided via \`setContext()\` that exactly matches this"Context Key Name". The corresponding value will be used for the parameter.

Plain JavaScript Example

Add this script after your chatbot embed script:

<!-- Place this script tag AFTER the chatbot embed script -->
<script>
// Function to attempt setting context
function setEasyFindAiContext() {
// Check if the chatbot API is ready
if (
window.easyfindai &&
typeof window.easyfindai.setContext === "function"
) {
const userData = {
userId: "user_123456", // Example: Get from your auth system
email: "user@example.com", // User's email
plan: "premium", // Subscription level
// Add any other fields your APIs might need
};
window.easyfindai.setContext(userData);
console.log("User context sent to EasyFindAi chatbot");
} else {
// If not ready, wait a bit and try again
console.warn("EasyFindAi context API not available yet, retrying...");
setTimeout(setEasyFindAiContext, 500); // Retry after 500ms
}
}
// Call when the page loads
document.addEventListener("DOMContentLoaded", setEasyFindAiContext);
</script>

React/Next.js Example

Create a Client Component to set the context:

// components/ChatbotContext.tsx
"use client";
import { useEffect } from "react";
import { useUser } from "@/hooks/useUser"; // Your user data hook
// Define window interface with chatbot properties
interface ExtendedWindow extends Window {
easyfindai?: {
setContext?: (data: any) => void;
};
}
export function ChatbotContextSetter() {
const { user } = useUser(); // Your hook to get authenticated user
useEffect(() => {
// Only proceed if we have user data
if (!user) return;
const win = window as ExtendedWindow;
// Function to set context with retry logic
const setContext = () => {
if (win.easyfindai?.setContext) {
win.easyfindai.setContext({
userId: user.id,
email: user.email,
plan: user.subscriptionTier,
// Add any other relevant user data
});
console.log("Context set for chatbot");
} else {
// Retry if the chatbot hasn't loaded yet
setTimeout(setContext, 500);
}
};
setContext();
}, [user]);
// This component doesn't render anything
return null;
}
// Use in your layout or page component:
// <ChatbotContextSetter />

Need Help with Your Framework?

While the method is the same (window.easyfindai.setContext(userData)), how you access user data and run this JavaScript depends on your specific website platform or framework (e.g., WordPress, Shopify, Wix, vanilla JS). Use the prompt template below to ask an AI assistant for guidance specific to your setup:

I need help setting the user context for the EasyFindAi chatbot on my website.
My website is built using: [Specify your framework/platform, e.g., WordPress with Elementor, Shopify (Liquid theme), Vanilla JavaScript, React, Angular, Vue, etc.]
The goal is to call the JavaScript function `window.easyfindai.setContext(userData)` after the chatbot script loads.
The `userData` object needs to contain specific key-value pairs. The **keys** in this object MUST exactly match the "Context Key Name" I will configure for my API parameters in EasyFindAi.
Here are the keys I need in the `userData` object, and where the corresponding values come from in my application:
* Key: "[e.g., userId]" - Value Source: [Describe where to get this value, e.g., 'A global JavaScript variable `myAppData.userId`', 'A data attribute on the body tag']
* Key: "[e.g., userEmail]" - Value Source: [Describe where to get this value, e.g., 'A global variable `myAppData.userEmail`', 'Need to fetch it via an internal API']
* Key: "[e.g., subscriptionTier]" - Value Source: [Describe where to get this value, e.g., 'A variable `myAppData.plan`']
* [Add any other required key-value pairs and their value sources]
Please provide a code snippet or steps specific to [Your Framework/Platform] showing how to:
1. Reliably access the data needed for the values listed above.
2. Construct the `userData` JavaScript object using the **exact keys** specified above.
3. Call `window.easyfindai.setContext(userData)` safely after the chatbot has loaded, ensuring the `window.easyfindai` object and `setContext` function exist (e.g., using checks or retries).

Important Notes

  • The keys in your \`userData\` object must exactly match the"Context Key Name" used in your API parameter configurations.
  • The context is not persisted between page reloads - you need to set it each time the page loads.
  • Context data should be set as early as possible after the chatbot loads.
  • Only include data necessary for your API parameters - avoid sending sensitive information.
  • Any changes to user data should trigger a new call to setContext().