Configuration reference

You configure askdare in two places:

defineBot checks the whole definition when your app starts. It throws a TypeError that lists every problem, for example:

[askdare] Invalid bot "Support": id use 1-48 lowercase letters, digits or dashes.

createChatHandler checks its own options when the route loads. It reads secrets on the first request, so next build never needs them.

Example

// askdare.config.ts
import { defineBot } from '@boldare/askdare';
import { orderStatus } from './tools';

// Other sites that may embed the chat, comma-separated.
const allowedOrigins = (process.env.ASKDARE_ALLOWED_ORIGINS ?? '')
  .split(',')
  .map((origin) => origin.trim())
  .filter(Boolean);

export const bots = [
  defineBot({
    id: 'support',
    model: process.env.ASKDARE_MODEL ?? '',
    instructions: ({ locale }) =>
      `You are the assistant on our website. Answer briefly. Reply in the visitor's language; default to ${locale}.`,
    tools: [orderStatus],
    knowledge: process.env.KB_VECTOR_STORE_ID
      ? { vectorStoreId: process.env.KB_VECTOR_STORE_ID }
      : undefined,
    attachments: { pdf: false },
    voice: process.env.ASKDARE_TRANSCRIBE_MODEL
      ? { model: process.env.ASKDARE_TRANSCRIBE_MODEL }
      : undefined,
    security: { allowedOrigins },
    limits: { dailyTokens: 500_000, messagesPerVisitorPerMinute: 5 },
    widget: {
      title: 'Support',
      locale: 'auto',
      starters: ['Where is my order?'],
      disclosure: { privacyUrl: '/privacy' },
      theme: 'aura',
    },
  }),
];

// app/api/chat/[...path]/route.ts
import { createChatHandler } from '@boldare/askdare/next';
import { upstashStore } from '@boldare/askdare-upstash';
import { bots } from '@/askdare.config';

// Must be a literal in this file; keep it above every bot's limits.turnTimeoutMs.
export const maxDuration = 300;

export const { GET, POST, DELETE } = createChatHandler({
  bots,
  limits: { store: upstashStore(), globalDailyTokens: 1_000_000 },
});

defineBot

defineBot(definition: BotDefinition): Bot. The types of every field are exported from @boldare/askdare: BotDefinition, BotContext, BotLimits, BotSecurity, KnowledgeConfig, AttachmentConfig, VoiceConfig and WidgetConfig.

Instructions

instructions is a string or a function. The function runs for each request and receives a BotContext:

Put no secrets in instructions. Assume visitors can make the model reveal them.

Knowledge

Fill the store with npx @boldare/askdare kb sync. See Knowledge base.

Attachments

Absent, attachments are off. attachments: {} turns them on with the defaults.

images and pdf can't both be false. See Attachments.

Voice

Absent, dictation is off.

See Voice input.

Security

security.allowedOrigins lists the other sites that may embed the chat. The app's own origin is always allowed. The browser enforces the list through the frame-ancestors policy of the chat page (ADR-0004).

Each entry must be an origin exactly as a browser writes it:

• https://, a host name and, only if it isn't the default, a port: https://www.example.com, https://shop.example.com:8443.
• http:// only for localhost, 127.0.0.1, [::1] and names that end in .localhost.
• No path, no trailing slash, no query and no wildcard (*).
• No default port (:443) and no capital letters.
• International domain names in their xn-- form.

The list holds at most 50 origins. Duplicates are dropped. A wrong entry fails with "must be an https origin like https://www.example.com (no path or wildcard; http only for localhost)".

To check that a site may embed the chat, run npx @boldare/askdare doctor --origin https://www.example.com.

Limits

Limits bound what visitors can cost (ADR-0004). Every limit applies per bot, and every value is a whole number.

What happens at a limit:

• Rates answer rate_limited, with a Retry-After header. So does maxTurns, which asks the visitor to start a new conversation.
• Token budgets answer budget_exceeded until midnight UTC. Before each model call, askdare reserves an estimate against dailyTokens, dailyTokensPerIp and the handler's globalDailyTokens. The estimate covers the conversation so far, the new message, maxOutputTokens, attached files and file search results. A bot with tools reserves the next call before each tool round, and answers without tools when a budget can't hold it. When the turn ends, the real usage replaces the estimate. A turn that fails or is cut off keeps the estimate charged.
• Speech budgets reserve voice.maxSeconds per dictation, then charge the duration OpenAI reports. When one is spent, dictation answers budget_exceeded until midnight UTC.
• maxInputChars rejects a longer message with invalid_input.

A few limits are fixed:

Per-IP limits depend on reading the client IP correctly. See trustProxy.

Widget

Everything in widget is sent to browsers. Never put secrets in it. Styling covers texts, languages and your own CSS. Themes covers presets, tokens and variants.

The text defaults come from the built-in dictionary of the configured language. The table shows the English ones, which 'auto' also uses. Texts ship in English and Polish.

createChatHandler

createChatHandler(options: ChatHandlerOptions): ChatHandlers returns GET, POST and DELETE for the catch-all route. Its types are exported from @boldare/askdare/next: ChatHandlerOptions, ChatHandlerLimitsOptions, ChatErrorReport, TrustProxy, ChatHandlers and RouteHandler.

A wrong basePath, a duplicate bot ID or an empty bots list throws a TypeError when the route loads. A missing key or a missing or weak secret doesn't stop the route from loading. Instead, requests that need it answer bot_unavailable, and onError receives the reason. In development (next dev), the chat itself says what to fix.

Handler limits

limits in createChatHandler applies to every bot of the handler.

trustProxy

• IPv6 addresses count per /64 network.
• Without a usable address, the request counts as unknown, and all such requests share the per-IP limits.
• Never expose next start without a proxy in front. Clients then choose their own IP.

See Deployment for setups with a CDN.

onError

onError receives server errors (status 500 and up), any error that ends an answer while it streams, and once a day a budget_exceeded report when a bot's or the global budget runs out (never a single visitor's). Use it for your monitoring. It never receives message contents or API keys. Don't throw from it.

import * as Sentry from '@sentry/nextjs';

export const { GET, POST, DELETE } = createChatHandler({
  bots,
  onError: ({ code, message, cause }) => {
    Sentry.captureException(cause ?? new Error(message), { tags: { askdare: code } });
  },
});

Without onError, askdare logs one console.error line with the code, what went wrong and a pointer to the troubleshooting guide.

ChatErrorReport:

code is one of invalid_input, unauthorized, session_expired, not_found, rate_limited, budget_exceeded, bot_unavailable, content_blocked (reserved, not sent yet), timeout, upstream_error or internal_error. The codes at status 500 and up are internal_error (500), upstream_error (502), bot_unavailable (503) and timeout (504). Protocol explains each one.

gallery

gallery: true serves the state gallery. <basePath>/embed/<bot>?gallery=<state>&preset=<preset>&scheme=<scheme> then renders a fixed state of the widget without calling the model.

It is for development and visual tests. Leave it off in production: npx @boldare/askdare doctor warns when it is on there.

The route file

The route needs one setting outside createChatHandler:

export const maxDuration = 300;

It must be a literal in the route file. It is the longest a streamed answer may take, so keep it above every bot's limits.turnTimeoutMs.

Environment variables

Read by askdare

The CLI reads .env.local and .env, or the file you pass with --env-file.

Conventions

The library doesn't read these. npx @boldare/askdare init, the starter and the demo site use them in askdare.config.ts and the route.

@boldare/askdare-upstash

A database from the Vercel Marketplace (Upstash for Redis) sets the KV_ names in the project. One created in the Upstash console shows the UPSTASH_ names to copy. The store reads them on first use, not at import.

Where to go next