VFI/O API Setup Guide

1. Getting Your VFI/O Authorization Key

Every Voiceflow agent you add to VFI/O Dashboard gets a unique VFI/O Authorization Key. This key identifies your specific agent and ensures data security.

Steps:

1. Log in to your VFI/O Dashboard
2. Go to Settings (gear icon in sidebar)
3. Find your agent in the list
4. Click the copy button next to the VFI/O Key

Your key looks like this: vfio_abc123xyz789...

Important: Keep this key secure. Anyone with this key can query your knowledge base.
If your key is compromised, you can generate a new one.

2. Setting Up Semantic Search API

Plan Requirement: Both Semantic Search and Tag Filter APIs require a Business or Business+ subscription plan.

The Semantic Search API uses AI to understand the meaning of a user's question and find the most relevant content from your knowledge base.

How It Works

Instead of just matching keywords, semantic search understands that:

• "How much does it cost?" is similar to "pricing"
• "What sport hoodies do you have?" should return sport hoodies, not classic hoodies

API Details

Required Headers

Request Body

{
  "query": "What sport hoodies do you have?",
  "threshold": 0.3,
  "chunks": 10
}

Tip: The threshold controls how similar a tag must be to match. A threshold of 0.3-0.4 catches more relevant results. The system then ranks results by content relevance, so lower thresholds are generally better.

Voiceflow Setup

1. Add an API Block to your Voiceflow canvas
2. Set Method to POST
3. Set URL to your semantic search endpoint
4. Add these Headers:
   • X-VFIO-Project-ID: {your_project_id}
   • X-VFIO-Auth-Key: {your_vfio_key}
   • Content-Type: application/json
5. Set Body to:

   {
     "query": "{last_utterance}",
     "threshold": 0.3,
     "chunks": 5
   }

6. Map the response to a variable (e.g., search_results)

Response Format

{
  "success": true,
  "query": "What sport hoodies do you have?",
  "chunks": [
    {
      "content": "Sport Hoodie Pro - Breathable fabric...",
      "documentId": "doc_123",
      "documentName": "Sport Hoodies Catalog",
      "tags": ["hoodie", "sport", "clothing"],
      "chunkId": "chunk_456",
      "contentSimilarity": "0.72"
    }
  ],
  "totalChunks": 5,
  "totalMatchedChunks": 15,
  "sourcesQueried": 2,
  "matchedTags": [
    { "tag": "hoodie", "similarity": "0.85" },
    { "tag": "sport", "similarity": "0.78" }
  ],
  "searchMode": "hybrid"
}

Using the Response in Voiceflow

Now you can use the variable {search_results} in a prompt or AI agent block to provide your answer.

(Optional) Code Block Example

This code combines just the content from the response for cleaner information for the LLM. In this example we store the response to {kbResponse} then using a code block we combine all content from the chunks:

const allContent = kbResponse.chunks.map(chunk => chunk.content);
search_results = allContent.join('\n\n');

3. Setting Up Tag Filter API

The Tag Filter API returns documents that have specific tags. Use this when you want exact matching rather than AI interpretation.

API Details

Required Headers

Same as Semantic Search:

• X-VFIO-Project-ID
• X-VFIO-Auth-Key

Request Body

{
  "tags": ["hoodie", "sport"],
  "operator": "AND",
  "chunks": 10
}

Operator Examples

OR Operator (default) - Returns documents with ANY of the tags:

{ "tags": ["sport", "classic"], "operator": "OR" }

Returns: Sport hoodies AND Classic hoodies

AND Operator - Returns documents with ALL tags:

{ "tags": ["hoodie", "sale"], "operator": "AND" }

Returns: Only hoodies that are also on sale

Response Format

{
  "success": true,
  "chunks": [
    {
      "content": "Sport Hoodie Pro - Now 20% off...",
      "documentId": "doc_123",
      "documentName": "Sport Hoodies Sale",
      "tags": ["hoodie", "sport", "sale"],
      "chunkId": "chunk_789"
    }
  ],
  "totalChunks": 5,
  "totalMatchedChunks": 12,
  "sourcesQueried": 3
}

4. Best Practices for Tagging

Good tagging makes your searches more accurate. Here are the best practices:

Be Specific

Use Hierarchical Tags

Create a tagging hierarchy for better filtering:

Category: clothing
Subcategory: hoodies
Type: sport

Tags: clothing, hoodies, sport-hoodie

This allows:

• Search all clothing: tags: ["clothing"]
• Search all hoodies: tags: ["hoodies"]
• Search specific type: tags: ["sport-hoodie"]

Use Multiple Tags Per Document

Each document should have 3-5 relevant tags:

Document: "Sport Hoodie Pro - Spring Collection"

Tags: sport-hoodie, spring-collection, mens, athletic, new-arrival

Consistent Naming

Pick a convention and stick with it:

• Use lowercase: sport-hoodie not Sport-Hoodie
• Use hyphens: return-policy not return_policy or returnpolicy
• Be consistent: mens everywhere, not mens, men, male

5. Example Use Cases

Example 1: Product Search

User asks: "Do you have any sport hoodies?"

Voiceflow API Block Body:

{
  "query": "{last_utterance}",
  "threshold": 0.3,
  "chunks": 5
}

Result: Returns sport hoodie products ranked by relevance, not classic hoodies.

Example 2: Category Browsing

User selects "Sale Items" from a menu

Voiceflow API Block Body:

{
  "tags": ["sale", "in-stock"],
  "operator": "AND",
  "chunks": 10
}

Result: Returns only items that are both on sale AND in stock.

Example 3: FAQ Search

User asks: "How do I return something?"

Voiceflow API Block Body:

{
  "query": "{last_utterance}",
  "threshold": 0.4,
  "chunks": 3
}

Result: Returns return policy content, even if user didn't say "return policy".

Example 4: Combining Tag Filter with Follow-up

First API call (tag filter):

{
  "tags": ["hoodies"],
  "operator": "OR",
  "chunks": 20
}

Then in conversation: "Which type? Sport or Classic?"

Second API call (semantic search on subset):

{
  "query": "sport",
  "threshold": 0.3,
  "chunks": 5
}

6. Troubleshooting

"Invalid VFI/O Authorization Key or Project ID"

Cause: The key or project ID doesn't match any agent in VFI/O.

Fix:

1. Go to VFI/O Settings and copy the key again
2. Make sure the Project ID matches your Voiceflow project
3. Ensure the agent is still active in VFI/O

"No tagged documents found"

Cause: Your documents don't have tags assigned.

Fix:

1. Go to Knowledge Base in VFI/O
2. Click on each document
3. Add relevant tags and save

"No semantically similar tags found"

Cause: The threshold is too high or tags don't match the query.

Fix:

1. Lower the threshold (try 0.2 or 0.3)
2. Add more descriptive tags to your documents
3. Check that your tags match what users might search for

Empty results but tags exist

Cause: Voiceflow API might be having issues fetching document content.

Fix:

1. Check the errors array in the response
2. Verify your Voiceflow API key is valid in VFI/O Settings
3. Ensure documents exist in Voiceflow's knowledge base

Slow response times

Cause: Many documents being processed.

Fix:

1. Reduce chunks parameter
2. Use more specific tags
3. Raise threshold to reduce processing

Quick Reference

Semantic Search (AI-powered)

POST https://dash.vfio.app/api/knowledge/semantic-search
Headers: X-VFIO-Project-ID, X-VFIO-Auth-Key
Body: { "query": "...", "threshold": 0.3, "chunks": 10 }

Tag Filter (Exact match)

POST https://dash.vfio.app/api/knowledge/filter
Headers: X-VFIO-Project-ID, X-VFIO-Auth-Key
Body: { "tags": ["..."], "operator": "AND", "chunks": 10 }

Need Help?

If you're having issues:

1. Check the troubleshooting section above
2. Verify your VFI/O Key and Project ID
3. Test with a simple query first
4. Contact support at support@vfio.app with your error message and response

Happy searching!