How to Integrate Bolt.new with IBM Watson

IBM Watson services are provisioned through IBM Cloud (cloud.ibm.com). Each Watson service is a separate resource with its own API key and endpoint URL. The free Lite tier gives you meaningful access to every core Watson service. To provision Watson Natural Language Understanding: log into cloud.ibm.com → click Catalog → search for 'Natural Language Understanding' → select the Lite plan → choose a region (Dallas, Frankfurt, London, Tokyo, or Sydney — choose the closest to your users or one required by your data residency needs) → click Create. After creation, go to the service's Manage page and click 'Show credentials' to reveal your API key and URL. The URL is region-specific (e.g., https://api.us-south.natural-language-understanding.watson.cloud.ibm.com/instances/your-instance-id). Repeat this process for other Watson services you need: Watson Assistant, Speech to Text, Text to Speech. Each service gets its own API key and URL — they are not interchangeable. Watson uses IAM authentication: your API key is used to generate short-lived Bearer tokens, but the ibm-watson SDK handles token refresh automatically when you pass an IamAuthenticator. For Watson Assistant specifically: after provisioning, you also need to create an Assistant and note its Assistant ID (a GUID). Go to your Watson Assistant service → click 'Launch Watson Assistant' → create a new assistant → go to Assistant Settings to find the Assistant ID.

1# Watson service credential format (from IBM Cloud → Service → Credentials):
2# Each service has its own:
3#   API_KEY: your-iam-api-key
4#   URL: https://api.{region}.{service}.watson.cloud.ibm.com/instances/{instance-id}
5
6# Example NLU URL format:
7# https://api.us-south.natural-language-understanding.watson.cloud.ibm.com/instances/abc123
8
9# Watson Assistant also needs:
10#   ASSISTANT_ID: the GUID of your assistant (found in Assistant Settings)

The ibm-watson package is IBM's official Node.js SDK for all Watson services. It is pure JavaScript — no native binaries, no node-gyp compilation — making it fully compatible with Bolt's WebContainer. The package uses the ibm-cloud-sdk-core package for authentication, which implements IAM token management automatically: when you initialize a service with an IamAuthenticator, the SDK fetches a Bearer token from IBM Cloud's IAM service and refreshes it before expiry. You never need to manage tokens manually. Each Watson service class in the SDK maps to one Watson API: NaturalLanguageUnderstandingV1, AssistantV2, TextToSpeechV1, SpeechToTextV1. They all follow the same initialization pattern: instantiate with an IamAuthenticator and the service URL, then call methods corresponding to API operations. Environment variable naming: since each Watson service has its own API key and URL, use service-specific variable names. Never mix up API keys across services — a Watson NLU API key will not authenticate Watson Assistant. Store all Watson credentials as server-side environment variables (no NEXT_PUBLIC_ prefix).

1// lib/watson.ts
2import NaturalLanguageUnderstandingV1 from 'ibm-watson/natural-language-understanding/v1';
3import AssistantV2 from 'ibm-watson/assistant/v2';
4import TextToSpeechV1 from 'ibm-watson/text-to-speech/v1';
5import { IamAuthenticator } from 'ibm-watson/auth';
6
7export const naturalLanguageUnderstanding = new NaturalLanguageUnderstandingV1({
8  version: '2022-04-07',
9  authenticator: new IamAuthenticator({
10    apikey: process.env.WATSON_NLU_API_KEY!,
11  }),
12  serviceUrl: process.env.WATSON_NLU_SERVICE_URL!,
13});
14
15export const assistant = new AssistantV2({
16  version: '2023-06-15',
17  authenticator: new IamAuthenticator({
18    apikey: process.env.WATSON_ASSISTANT_API_KEY!,
19  }),
20  serviceUrl: process.env.WATSON_ASSISTANT_SERVICE_URL!,
21});
22
23export const textToSpeech = new TextToSpeechV1({
24  authenticator: new IamAuthenticator({
25    apikey: process.env.WATSON_TTS_API_KEY!,
26  }),
27  serviceUrl: process.env.WATSON_TTS_SERVICE_URL!,
28});

Watson Assistant is the most popular Watson service for Bolt developers. Unlike OpenAI which requires you to manage conversation history and write all business logic in prompts, Watson Assistant provides a structured dialog management system: you define intents (what users want), entities (key concepts), and dialog flows (how the assistant responds). This makes it excellent for customer service bots, FAQ systems, and guided workflows where you want predictable, auditable behavior. The Watson Assistant V2 API requires a session-based conversation model. Each conversation starts with creating a session (returns a session_id), then you send messages using that session_id. Sessions expire after a period of inactivity (configurable, default 5 minutes for Lite tier). Your API route must handle session creation for new conversations and message sending for existing ones. The response from Watson Assistant includes the assistant's response text, intents that were recognized, entities found in the user input, and any actions the assistant wants to take (like calling a webhook or ending the conversation). Extract the generic response array and filter for type 'text' to get the response text — Watson can return multiple response types including options (buttons) and pauses.

1// app/api/watson/assistant/route.ts
2import { NextResponse } from 'next/server';
3import { assistant } from '@/lib/watson';
4
5const ASSISTANT_ID = process.env.WATSON_ASSISTANT_ID!;
6
7async function createSession(): Promise<string> {
8  const result = await assistant.createSession({ assistantId: ASSISTANT_ID });
9  return result.result.session_id;
10}
11
12export async function POST(request: Request) {
13  try {
14    let { message, sessionId } = await request.json();
15
16    if (!sessionId) {
17      sessionId = await createSession();
18    }
19
20    let result;
21    try {
22      result = await assistant.message({
23        assistantId: ASSISTANT_ID,
24        sessionId,
25        input: { message_type: 'text', text: message },
26      });
27    } catch (err: unknown) {
28      const e = err as { statusCode?: number };
29      if (e.statusCode === 404) {
30        // Session expired — create a new one
31        sessionId = await createSession();
32        result = await assistant.message({
33          assistantId: ASSISTANT_ID,
34          sessionId,
35          input: { message_type: 'text', text: message },
36        });
37      } else throw err;
38    }
39
40    const responses = result.result.output.generic || [];
41    const texts = responses
42      .filter((r: { response_type: string }) => r.response_type === 'text')
43      .map((r: { text: string }) => r.text);
44
45    return NextResponse.json({
46      response: texts.join(' '),
47      sessionId,
48    });
49  } catch (error: unknown) {
50    const e = error as { message: string };
51    return NextResponse.json({ error: e.message }, { status: 500 });
52  }
53}

Watson Natural Language Understanding analyzes text to extract structured insights: sentiment (positive/negative/neutral with a score from -1 to +1), entities (named things — people, organizations, locations, dates, currencies), keywords (important phrases), categories (content classification into a 5-level hierarchy), concepts (abstract ideas even if not explicitly mentioned), and relations (relationships between entities). The NLU API takes text (or a URL to analyze) and a features object specifying what analysis to perform. Each feature adds processing time and costs API credits — only request features you'll use. For a feedback analysis dashboard, sentiment and keywords are most useful. For a content tagging system, categories and concepts are better. For a contact extraction tool, entities is the key feature. NLU analysis works in the Bolt preview since it's a standard HTTPS API call. The response includes confidence scores for each result, which you can use to filter out low-confidence extractions before displaying them to users.

1// app/api/watson/analyze/route.ts
2import { NextResponse } from 'next/server';
3import { naturalLanguageUnderstanding } from '@/lib/watson';
4import NaturalLanguageUnderstandingV1 from 'ibm-watson/natural-language-understanding/v1';
5
6export async function POST(request: Request) {
7  try {
8    const { text } = await request.json();
9
10    if (!text || text.trim().length < 10) {
11      return NextResponse.json(
12        { error: 'Text must be at least 10 characters' },
13        { status: 400 }
14      );
15    }
16
17    const analysis = await naturalLanguageUnderstanding.analyze({
18      text,
19      features: {
20        sentiment: {},
21        entities: {
22          limit: 5,
23          mentions: false,
24        } as NaturalLanguageUnderstandingV1.EntitiesOptions,
25        keywords: {
26          limit: 5,
27          sentiment: false,
28        } as NaturalLanguageUnderstandingV1.KeywordsOptions,
29        categories: {
30          limit: 3,
31        } as NaturalLanguageUnderstandingV1.CategoriesOptions,
32      },
33    });
34
35    return NextResponse.json({
36      sentiment: analysis.result.sentiment?.document,
37      entities: analysis.result.entities,
38      keywords: analysis.result.keywords,
39      categories: analysis.result.categories,
40    });
41  } catch (error: unknown) {
42    const e = error as { message: string };
43    return NextResponse.json({ error: e.message }, { status: 500 });
44  }
45}

Watson service integrations work fully in Bolt's WebContainer during development — all API calls are outbound HTTPS. Before deploying to production, there are two important Watson-specific considerations: service plan limits and IAM token management at scale. Free Lite tier limits are per-calendar-month. Watson NLU: 30,000 API calls/month. Watson Assistant: 10,000 API calls/month, 1,000 unique monthly active users. Watson Text to Speech: 10,000 characters/month. If your app exceeds these limits, requests return 429 errors. Upgrade to the Plus or Standard plans through IBM Cloud — pricing is per API call with tiered volume discounts. For production deployment, deploy your Bolt project to Netlify via Settings → Applications → Netlify. In Netlify's Site Settings → Environment Variables, add all your Watson environment variables (WATSON_NLU_API_KEY, WATSON_NLU_SERVICE_URL, etc.). Do not use NEXT_PUBLIC_ prefixes — Watson API keys are sensitive credentials that must remain server-side. IAM token caching: the ibm-watson SDK handles IAM token refresh automatically, but in a serverless environment (Netlify Functions, Vercel), each function invocation may initialize a new SDK instance and fetch a new IAM token. This adds 200-500ms to cold-start invocations. To mitigate this, initialize Watson service instances as module-level constants (not inside request handlers) so they are cached across warm invocations in the same Lambda container.

1// app/api/watson/health/route.ts
2import { NextResponse } from 'next/server';
3import { naturalLanguageUnderstanding } from '@/lib/watson';
4
5export async function GET() {
6  try {
7    await naturalLanguageUnderstanding.analyze({
8      text: 'Testing Watson NLU health check connectivity.',
9      features: { sentiment: {} },
10    });
11    return NextResponse.json({ status: 'ok', service: 'watson-nlu' });
12  } catch (error: unknown) {
13    const e = error as { message: string; statusCode?: number };
14    const isRateLimit = e.statusCode === 429;
15    return NextResponse.json(
16      {
17        status: isRateLimit ? 'rate_limited' : 'error',
18        message: e.message,
19      },
20      { status: isRateLimit ? 429 : 500 }
21    );
22  }
23}