@asktext/next

Next.js integration layer for AskText voice Q&A system.

What it provides

• Webhook handler: Processes Vapi tool calls and returns relevant article passages
• Voice quota system: Redis-based rate limiting for voice assistant usage
• Edge runtime: Optimized for Vercel Edge Functions with low latency
• Auto-initialization: CLI tool to scaffold API routes in your Next.js app

Installation

npm install @asktext/next @upstash/redis

Quick Setup

1. Initialize Routes

npx asktext-init

This creates:

• app/api/asktext/webhook/route.ts - Main webhook handler
• app/api/voice/start/route.ts - Quota check endpoint
• app/api/voice/end/route.ts - Usage tracking endpoint
• .env.local.example - Environment variable template

2. Environment Variables

# Required
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://...

# Optional (for voice quota)
REDIS_URL=redis://...
UPSTASH_REDIS_REST_URL=https://...
UPSTASH_REDIS_REST_TOKEN=...

# Frontend (for React components)
NEXT_PUBLIC_VAPI_PUBLIC_KEY=pk_...
NEXT_PUBLIC_VAPI_ASSISTANT_ID=asst_...

Usage

Basic Webhook Handler

// app/api/asktext/webhook/route.ts
import { createAskTextWebhook } from '@asktext/next';

const { OPTIONS, POST } = createAskTextWebhook({
  openAIApiKey: process.env.OPENAI_API_KEY!,
});

export { OPTIONS, POST };

With Redis Rate Limiting

import { createAskTextWebhook } from '@asktext/next';
import { Redis } from '@upstash/redis';

const redis = Redis.fromEnv();

const { OPTIONS, POST } = createAskTextWebhook({
  openAIApiKey: process.env.OPENAI_API_KEY!,
  redis,
  dailyQuota: 100, // max calls per IP per day
});

export { OPTIONS, POST };

Voice Quota Handlers

// app/api/voice/start/route.ts
export { quotaStart as POST } from '@asktext/next';

// app/api/voice/end/route.ts  
export { quotaEnd as POST } from '@asktext/next';

Advanced Configuration

Custom Database Store

import { createAskTextWebhook } from '@asktext/next';
import { createCustomStore } from './my-vector-store';

const store = createCustomStore();

const { OPTIONS, POST } = createAskTextWebhook({
  openAIApiKey: process.env.OPENAI_API_KEY!,
  store, // Use custom store instead of default Prisma
});

Custom Quota Limits

import { createVoiceQuotaHandlers } from '@asktext/next';
import { Redis } from '@upstash/redis';

const redis = Redis.fromEnv();

const { start, end } = createVoiceQuotaHandlers({
  redis,
  dailySeconds: 600, // 10 minutes per IP per day
});

export { start as POST };

VAPI Assistant Setup

Tool Creation

1. Create Custom Tool from VAPI Dashboard
2. Give name (retrieve_passage), description, keep async and strict toggles unchecked.
3. Add Parameters (in JSON mode):

{
  "type": "object",
  "properties": {
    "k": {
      "description": "How many passages to return",
      "type": "integer"
    },
    "query": {
      "description": "User question",
      "type": "string"
    },
    "articleId": {
      "description": "Slug of the article",
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

4. Use ngrok (ngrok http <port_number>) to create a Server URL if on development, else just add your domain if in production, followed by /api/webhook Examples: https://fe2e544f8cc4.ngrok-free.app/api/vapi-webhook, https://www.csnobs.com/api/vapi-webhook

5. Rest are optional, approve tool creation.

Assistant Creation

1. Create Blank Assistant
2. Choose models (I chose Gemini 1.5 Flash, 11Labs Knightley Javier - calm, gentle via Eleven_turbo_v2_5 and 11labs Scribe transcriber)
3. Add First Message:

Hey, what would you like to know about the article? You can ask me a general question regarding the content or ask me to summarise a specific portion you want and ask clarifying questions on it!

4. Add System Prompt:

You are CSNoBS ArticleBot, a voice-first expert on the current article.

You have one tool:
{ "name": "retrieve_passage",
  "arguments": { "query": "<string>" } }

WHEN (and only when) the user asks about the article’s content,
ALWAYS respond with a tool call first.

After the tool returns a Passages list:
• Answer ONLY using those passages.
• Never exceed **300 spoken words** in a single turn – even if the user says “go into detail”.
• If passages are empty, say “I’m sorry, that isn’t covered in this article.”

Example 1  
user: What’s DOM parsing?  
assistant (tool call):  
{ "name": "retrieve_passage",
  "arguments": { "query": "DOM parsing" } }

Example 2  
user: Production vs development architecture?  
assistant (tool call):  
{ "name": "retrieve_passage",
  "arguments": { "query": "production vs development architecture" } }

Formatting after tool result:  
“Sure! … <answer>. Let me know if you’d like to dive deeper!”

5. Connect the previously created tool and approve assistant creation.

6. Add the Tool and Assistant API Keys in your environment file

Architecture

Webhook Flow

1. Vapi calls → /api/asktext/webhook
2. Extract question from tool call payload
3. Retrieve passages using semantic search
4. Return context to Vapi assistant
5. Assistant responds using retrieved information

Quota Flow

1. Frontend calls → /api/voice/start (pre-flight check)
2. Voice call begins → Vapi handles conversation
3. Call ends → Frontend posts duration to /api/voice/end
4. Redis tracks total seconds per IP per 24h window

Environment Setup

Development

# .env.local
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://localhost:5432/mydb
REDIS_URL=redis://localhost:6379

NEXT_PUBLIC_VAPI_PUBLIC_KEY=pk_...
NEXT_PUBLIC_VAPI_ASSISTANT_ID=asst_...

Production (Vercel)

Set environment variables in Vercel dashboard:

• All the above variables
• Use Upstash Redis for REDIS_URL
• Use Vercel Postgres or external DB for DATABASE_URL

Troubleshooting

Common Issues

"Module not found" errors

• Ensure @asktext/core is installed as a dependency
• Check that database schema includes ArticleChunk model

Webhook timeouts

• Verify OPENAI_API_KEY is valid
• Check database connection and embeddings exist
• Monitor Vercel function logs

Quota not working

• Confirm REDIS_URL is set and accessible
• Check that frontend calls both /start and /end endpoints
• Verify IP address detection in serverless environment

License

MIT