Skip to main content
Integrate Moss semantic search into a VAPI voice agent using the vapi-moss package. This setup lets your conversational AI perform sub-10ms knowledge base lookups through VAPI’s Custom Knowledge Base webhook, so your agent can answer questions instantly during live calls.
Note: For a complete FastAPI server example, see the vapi-moss app.

​
Why use Moss with VAPI?

VAPI’s Custom Knowledge Base webhook fires on every user turn, expecting fast document retrieval. Moss responds in under 10ms, keeping voice interactions natural and fluid without added latency from traditional RAG pipelines.

​
Required tools

  • Moss account with project credentials
  • VAPI account with a Conversational AI agent
  • Python 3.10+

​
Integration guide

1

Installation

pip install vapi-moss
2

Environment setup

Create a .env file in your project root with your credentials.
.env
# Moss Credentials
MOSS_PROJECT_ID=your_project_id
MOSS_PROJECT_KEY=your_project_key
MOSS_INDEX_NAME=your_index_name

# VAPI Webhook Secret (from your VAPI Knowledge Base config)
VAPI_WEBHOOK_SECRET=your_webhook_secret
3

Search and verify signatures

Use MossVapiSearch to query your index and verify_vapi_signature to validate incoming webhook requests.
from vapi_moss import MossVapiSearch, verify_vapi_signature

# Initialize the search client
search = MossVapiSearch(
    index_name="my-faq-index",
    top_k=5,
    alpha=0.8,
)

# Load the index at startup
await search.load_index()

# Search
result = await search.search("How do I return an item?")
print(result.documents)    # [{"content": "...", "similarity": 0.92}, ...]
print(result.time_taken_ms)  # 3

# Verify webhook signatures
is_valid = verify_vapi_signature(
    raw_body=request_bytes,
    signature_header=headers["x-vapi-signature"],
    secret="your-webhook-secret",
)
4

Configure VAPI

In your VAPI dashboard:
  1. Navigate to your agent’s settings
  2. Under Knowledge Base, select Custom Knowledge Base
  3. Set the webhook URL to your server endpoint (e.g., https://your-server.com/webhook)
  4. Add your webhook secret to enable signature verification

​
Configuration

​
MossVapiSearch

ParameterTypeDefaultDescription
project_idstrNoneYour Moss Project ID. Falls back to MOSS_PROJECT_ID env var.
project_keystrNoneYour Moss Project Key. Falls back to MOSS_PROJECT_KEY env var.
index_namestrRequiredThe name of the Moss index to query.
top_kint5Number of results to retrieve per query.
alphafloat0.8Hybrid search weighting. 0.0 = keyword only, 1.0 = semantic only.