How to Integrate with Flowise

Learn how to use the SnackPrompt AI Engine API as an external knowledge source in Flowise chatbots and AI workflows.

Overview

Flowise is a visual tool for building LLM applications. It offers several ways to integrate external APIs:

Method	Use Case	Description
Custom Tool	Agent with tools	Agent decides when to query the API
HTTP Request Node	Direct RAG	Call API at specific point in the flow
Custom Retriever	Replace vector store	Use external API instead of built-in retriever
API Chain	Sequential calls	Chain multiple API calls together

Integration Architecture

┌─────────────────────────────────────────────────────────┐
│                      Flowise                            │
│  ┌─────────────┐    ┌─────────────┐    ┌────────────┐   │
│  │    Chat     │───▶│  LLM Chain  │───▶│  Response │   │
│  │   Input     │    │  or Agent   │    │            │   │
│  └─────────────┘    └──────┬──────┘    └────────────┘   │
│                            │                            │
│                     ┌──────▼──────┐                     │
│                     │ Custom Tool │                     │
│                     │  or Chain   │                     │
│                     └──────┬──────┘                     │
└────────────────────────────┼────────────────────────────┘
                             │
                             ▼
              ┌──────────────────────────────┐
              │  SnackPrompt AI Engine API   │
              │  /v1/kb/search or /v1/kb/chat│
              └──────────────────────────────┘

---

Method 1: Custom Tool (Recommended for Agents)

Use when you want the agent to autonomously decide when to search your knowledge base.

Step 1: Create a Custom Tool

1. In Flowise, go to Tools in the sidebar

2. Click Add New

3. Configure the tool:

Tool Configuration:

Field	Value
Name	search_knowledge_base
Description	Use this tool to search for information in the company knowledge base. Send a natural language query to find relevant documents about products, policies, procedures, etc. Returns relevant text snippets.

Step 2: Configure the Tool Code

const fetch = require('node-fetch');

const searchKnowledgeBase = async (query) => {
    const response = await fetch('https://api-integrations.snackprompt.com/v1/kb/search', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'x-api-key': process.env.SNACKPROMPT_API_KEY
        },
        body: JSON.stringify({
            query: query,
            filters: {
                tenant_id: process.env.SNACKPROMPT_TENANT_ID
            },
            limit: 5
        })
    });

    const data = await response.json();

    if (!data.items || data.items.length === 0) {
        return 'No relevant information found in the knowledge base.';
    }

    return data.items
        .map((item, index) => `[${index + 1}] ${item.payload.original_text}`)
        .join('\n\n');
};

module.exports = { searchKnowledgeBase };

Step 3: Build the Agent Flow

1. Add Chat Trigger node

2. Add Tool Agent or OpenAI Function Agent node

3. Connect your Custom Tool

4. Add Chat Model (OpenAI, Anthropic, etc.)

[Chat Trigger] → [Tool Agent] → [Response]
                      │
                      ├── [Chat Model: GPT-4]
                      └── [Custom Tool: search_knowledge_base]

---

Method 2: HTTP Request Chain

Use when you want a deterministic flow where the search always happens.

Step 1: Create the Flow

1. Add Chat Trigger node

2. Add HTTP Request node

3. Add LLM Chain node for response generation

Step 2: Configure HTTP Request Node

Request Configuration:

Field	Value
Method	POST
URL	https://api-integrations.snackprompt.com/v1/kb/search
Headers	See below
Body	See below

Headers:

{
  "Content-Type": "application/json",
  "x-api-key": "{{$env.SNACKPROMPT_API_KEY}}"
}

Body:

{
  "query": "{{$input}}",
  "filters": {
    "tenant_id": "{{$env.SNACKPROMPT_TENANT_ID}}"
  },
  "limit": 5
}

Step 3: Process and Format Results

Add a JavaScript Function node to format the results:

function formatResults(data) {
    if (!data.items || data.items.length === 0) {
        return 'No relevant information found.';
    }

    return data.items
        .map((item, index) => `[${index + 1}] ${item.payload.original_text}`)
        .join('\n\n');
}

return formatResults($input);

Step 4: Generate Response with LLM

Add LLM Chain with prompt:

You are a helpful assistant. Answer the user's question based ONLY on the following context.

Context:
{context}

User Question: {question}

If the context doesn't contain relevant information, say "I don't have information about that."

---

Method 3: Chat Endpoint for Complete Responses

Use the /v1/kb/chat endpoint when you want the API to handle all the RAG.

Simple Chatbot Flow

[Chat Trigger] → [HTTP Request: /chat] → [Parse Response] → [Output]

HTTP Request Configuration

Field	Value
URL	https://api-integrations.snackprompt.com/v1/kb/chat
Method	POST

Headers:

{
  "Content-Type": "application/json",
  "x-api-key": "{{$env.SNACKPROMPT_API_KEY}}"
}

Body:

{
  "query": "{{$input}}",
  "filters": {
    "tenant_id": "{{$env.SNACKPROMPT_TENANT_ID}}",
    "tag_names": ["Support", "FAQ"]
  }
}

Parse Response

Extract the answer field from the response:

return $input.answer;

---

Method 4: Custom Retriever Node

For advanced users who want to replace Flowise's built-in retrievers.

Step 1: Create Custom Retriever

Create a custom node that implements the retriever interface:

const { BaseRetriever } = require('langchain/schema/retriever');
const { Document } = require('langchain/document');

class SnackPromptRetriever extends BaseRetriever {
    constructor(config) {
        super();
        this.apiKey = config.apiKey;
        this.tenantId = config.tenantId;
        this.limit = config.limit || 5;
        this.tagNames = config.tagNames || [];
    }

    async getRelevantDocuments(query) {
        const response = await fetch('https://api-integrations.snackprompt.com/v1/kb/search', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'x-api-key': this.apiKey
            },
            body: JSON.stringify({
                query: query,
                filters: {
                    tenant_id: this.tenantId,
                    tag_names: this.tagNames
                },
                limit: this.limit
            })
        });

        const data = await response.json();

        return data.items.map(item => new Document({
            pageContent: item.payload.original_text,
            metadata: {
                id: item.payload.snack_item_id,
                score: item.score
            }
        }));
    }
}

module.exports = { SnackPromptRetriever };

Step 2: Use in Conversational Retrieval Chain

Connect your custom retriever to a Conversational Retrieval QA Chain:

[Chat Trigger] → [Conversational Retrieval QA Chain] → [Response]
                              │
                              ├── [Chat Model]
                              ├── [Custom Retriever: SnackPrompt]
                              └── [Memory]

---

Practical Use Cases

1. Simple Support Chatbot

[Chat Trigger] → [HTTP: /chat] → [Response]

Direct integration for simple Q&A chatbots.

2. Agent with Multiple Tools

[Chat Trigger] → [Tool Agent] → [Response]
                      │
                      ├── [Tool: search_knowledge_base]
                      ├── [Tool: search_products]
                      └── [Tool: calculator]

Agent that can search different knowledge bases and perform calculations.

3. RAG with Memory

[Chat Trigger] → [Conversational Retrieval Chain] → [Response]
                              │
                              ├── [Custom Retriever]
                              └── [Buffer Memory]

Chatbot that remembers conversation history while retrieving from knowledge base.

4. Multi-Source RAG

[Chat Trigger] → [Router] → [Merge] → [LLM Chain] → [Response]
                    │
                    ├── [HTTP: tag=Sales]
                    └── [HTTP: tag=Support]

Search multiple knowledge bases and combine results.

5. Hybrid Search

[Chat Trigger] → [Parallel]
                    │
                    ├── [HTTP: SnackPrompt Search]
                    └── [Vector Store: Local]
                    │
                    ▼
               [Merge Results] → [LLM Chain] → [Response]

Combine external API results with local vector store.

---

Environment Variables

Set these in your Flowise deployment:

Variable	Description
SNACKPROMPT_API_KEY	Your SnackPrompt API key
SNACKPROMPT_TENANT_ID	Your tenant ID

Setting Environment Variables

Docker:

environment:
  - SNACKPROMPT_API_KEY=your_api_key
  - SNACKPROMPT_TENANT_ID=your_tenant_id

Local:

export SNACKPROMPT_API_KEY=your_api_key
export SNACKPROMPT_TENANT_ID=your_tenant_id

---

Configuration Tips

1. Tool Description is Critical

For agents, the tool description determines when it's used:

✅ Good description:
"Search the company knowledge base for information about products,
pricing, policies, and procedures. Use when the user asks about
company-specific information that requires factual answers."

❌ Bad description:
"Search API"

2. Limit Results

Too many results can confuse the LLM:

{
    "limit": 3  // Start small, increase if needed
}

3. Use Filters

Filter by tags when you know the context:

{
    "filters": {
        "tenant_id": "...",
        "tag_names": ["FAQ", "Products"]
    }
}

4. Handle Errors

Add error handling in your JavaScript nodes:

try {
    const response = await fetch(url, options);
    if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
    }
    return await response.json();
} catch (error) {
    console.error('Search failed:', error);
    return { items: [], error: error.message };
}

5. Cache Responses

For frequently asked questions, consider caching:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function cachedSearch(query) {
    const cacheKey = query.toLowerCase().trim();
    const cached = cache.get(cacheKey);

    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
        return cached.data;
    }

    const data = await searchKnowledgeBase(query);
    cache.set(cacheKey, { data, timestamp: Date.now() });
    return data;
}

---

Complete Example: Customer Support Bot

Flow Structure

1. Chat Trigger: Receives user message

2. Tool Agent: Processes with GPT-4

3. Custom Tools: Search knowledge base

4. Response: Returns answer with sources

Agent System Prompt

You are a helpful customer support assistant for Company X.

Your capabilities:
- Search the knowledge base for product information, policies, and FAQs
- Provide accurate answers based on the retrieved information
- Cite sources when providing information

Guidelines:
- Always search the knowledge base before answering product-related questions
- If you can't find relevant information, say so honestly
- Be concise but thorough in your responses
- Format responses with bullet points when listing multiple items

Tool Configuration

Tool	Name	Description
Search	search_kb	Search for product info, policies, and FAQs
Search Products	search_products	Search specifically for product details and pricing

---

Troubleshooting

Error: "tenant_id is required"

Ensure tenant_id is inside the filters object:

// ❌ Wrong
{ "query": "...", "tenant_id": "..." }

// ✅ Correct
{ "query": "...", "filters": { "tenant_id": "..." } }

Agent doesn't use the tool

1. Improve the tool description

2. Add examples in the system prompt

3. Test with explicit queries like "search for..."

Empty results

1. Verify environment variables are set

2. Check tenant_id is correct

3. Remove tag filters to search all content

4. Test the API directly with curl

Timeout errors

1. Increase timeout in HTTP Request node

2. Reduce the limit parameter

3. Check network connectivity

---

Related

• Endpoints Reference

• Available Filters

• Error Hand

External Resources

• Flowise Documentation

• Flowise GitHub

• LangChain Custom Retrievers

• Building Custom Tools in Flowise