Creating Custom Knowledge Bases for Your Voice AI Assistants

​

What is Vapi’s Knowledge Base?

Our Knowledge Base is a collection of custom documents that contain information on specific topics or domains. By integrating a Knowledge Base into your voice AI assistant, you can enable it to provide more accurate and informative responses to user queries.

​

Why Use a Knowledge Base?

Using a Knowledge Base with your voice AI assistant offers several benefits:

• Improved accuracy: By integrating custom documents into your assistant, you can ensure that it provides accurate and up-to-date information to users.
• Enhanced capabilities: A Knowledge Base enables your assistant to answer complex queries and provide detailed responses to user inquiries.
• Customization: With a Knowledge Base, you can tailor your assistant’s responses to specific domains or topics, making it more effective and informative.

​

How to Create a Knowledge Base

To create a Knowledge Base, follow these steps:

​

Step 1: Upload Your Documents

Navigate to Overview > Documents and upload your custom documents in Markdown, PDF, plain text, or Microsoft Word (.doc and .docx) format to Vapi’s Knowledge Base.

​

Step 2: Create an Assistant

Create a new assistant in Vapi and, on the right sidebar menu, select the document you’ve just added to the Knowledge Base feature.

​

Step 3: Configure Your Assistant

Customize your assistant’s system prompt to utilize the Knowledge Base for responding to user queries.

​

Best Practices for Creating Effective Knowledge Bases

• Organize Your documents: Organize your documents by topic or category to ensure that your assistant can quickly retrieve relevant information.
• Use Clear and concise language: Use clear and concise language in your documents to ensure that your assistant can accurately understand and respond to user queries.
• Keep your documents up-to-date: Regularly update your documents to ensure that your assistant provides the most accurate and up-to-date information.

​

Custom Knowledge Base Documentation

​

Overview

This guide is about setting up your own custom knowledge base. You can hook up your own server to handle knowledge requests, which are then sent to a language model to generate responses based on the info you provide.

​

Custom Knowledge Base Class

​

CustomKnowledgeBase

This is where you define your custom knowledge base setup. It tells the system where to send requests and how to handle them.

Properties:

• provider: Set this to custom-knowledge-base since you’re using a custom setup.
• server: This is where you configure your server’s details, like the URL, secret key (if you have one), and the request timeout.

​

Server Configuration

​

Server

This class defines your server settings, which is where the system will send all the requests.

Properties:

• url: The endpoint where requests will be sent. Needs to be a valid HTTPS URL. Example: https://my-restaurant-knowledgebase.com.

• secret: Optional. A secret key to add as a header (x-vapi-secret) for extra security.

• timeoutSeconds: How long to wait for a response before timing out. Default is 20 seconds, but you can set it anywhere between 1 and 60 seconds.

​

Making a Request

When the system needs info from your knowledge base, it sends a POST request to your server’s URL.

​

Example 1: Restaurant Opening Hours

Let’s say a user asks for your restaurant’s opening hours. Here’s the request:

curl -X POST https://my-restaurant-knowledgebase.com \
  -H "Content-Type: application/json" \
  -H "x-vapi-secret: your-secret-key" \
  -d '{
    "message": {
      "type": "knowledge-base-request",
      "messages": [
        {
          "role": "user",
          "content": "What are your opening hours?"
        }
      ]
    }
  }'

​

Expected Response

When your server gets the request, it’ll return one of two things:

1. A direct answer that the assistant can speak or display.
2. A list of documents that the system will use to generate a reply.

​

Example 1: Direct Response for Opening Hours

{
  "message": {
    "role": "assistant",
    "content": "Our restaurant is open from 10 AM to 9 PM, Monday to Saturday."
  }
}

The assistant will say:
“Our restaurant is open from 10 AM to 9 PM, Monday to Saturday.”

​

Example 2: Document-Based Response for Opening Hours

{
  "documents": [
    {
      "content": "The restaurant is open from 10 AM to 9 PM, Monday to Saturday. Sunday hours are 11 AM to 6 PM.",
      "similarity": 1
    },
    {
      "content": "We are closed on Thanksgiving and Christmas.",
      "similarity": 0.9
    }
  ]
}

The assistant might respond with:
“We’re open from 10 AM to 9 PM, Monday to Saturday, and from 11 AM to 6 PM on Sundays.”

​

Server Message Request Structure

ServerMessageKnowledgeBaseRequest is how the system sends messages to your server.

• type: Always "knowledge-base-request" to ask for info from the knowledge base.
• messages: The user’s question or conversation context, which gets sent to your server.
• messagesOpenAIFormatted: If you’re using OpenAI or something similar, this is where you send formatted messages.

​

Response Message Structure

ServerMessageResponseKnowledgeBaseRequest defines how your server should respond.

• documents: An array of documents, each containing a piece of content (e.g., a menu item or a policy) and its relevance (similarity score).
• message: Optional. This is where you can send a direct response instead of letting the system process the documents.

​

Choosing Between Response Types

• Custom Message Response: Use this when you already have a simple answer ready to go, like stating opening hours.

• Document-Based Response: Use this when the assistant requires to be provided with more context or pull from additional documents more context or detail, like explaining the full menu or availability rules.

By following these guidelines, you can create a comprehensive Knowledge Base that enhances the capabilities of your voice AI assistant and provides valuable information to users.