How to Integrate Intercom with V0

The Intercom Messenger widget is a JavaScript snippet that initializes the chat bubble on your site. In Next.js App Router, the correct place to add it is in your root layout (app/layout.tsx) using a client component — the widget calls browser APIs (window.Intercom) which are not available in Server Components. Create a separate IntercomProvider client component that uses useEffect to load and initialize the Intercom script, then import it into your root layout. The Intercom initialization accepts user identification data: user_id (your internal user ID), email, name, and custom attributes like plan, created_at (Unix timestamp of account creation), and any product-specific data you want visible to support agents. If your app uses an authentication solution like Clerk or NextAuth, read the logged-in user's data in the provider component and pass it to the Intercom boot call. The Intercom App ID is safe to expose in client-side code — it is a public identifier, not a secret. Set it as NEXT_PUBLIC_INTERCOM_APP_ID in your Vercel environment variables so V0-generated components can access it. For apps requiring identity verification (to prevent users from impersonating each other in Intercom), you will also need to generate an HMAC hash of the user ID using your Intercom Identity Verification secret and pass it as user_hash — generate this hash in a server action or API route, never in client code, and pass it down as a prop to the provider component.

1// components/IntercomProvider.tsx
2'use client';
3
4import { useEffect } from 'react';
5
6declare global {
7  interface Window {
8    Intercom: (...args: unknown[]) => void;
9    intercomSettings: Record<string, unknown>;
10  }
11}
12
13interface IntercomProviderProps {
14  userId?: string;
15  email?: string;
16  name?: string;
17  createdAt?: number; // Unix timestamp
18  customAttributes?: Record<string, string | number | boolean>;
19  children: React.ReactNode;
20}
21
22export function IntercomProvider({
23  userId,
24  email,
25  name,
26  createdAt,
27  customAttributes,
28  children,
29}: IntercomProviderProps) {
30  const appId = process.env.NEXT_PUBLIC_INTERCOM_APP_ID;
31
32  useEffect(() => {
33    if (!appId) return;
34
35    // Load Intercom script
36    const script = document.createElement('script');
37    script.src = `https://widget.intercom.io/widget/${appId}`;
38    script.async = true;
39    document.head.appendChild(script);
40
41    script.onload = () => {
42      const bootData: Record<string, unknown> = {
43        app_id: appId,
44        ...customAttributes,
45      };
46
47      if (userId) {
48        bootData.user_id = userId;
49        bootData.email = email;
50        bootData.name = name;
51        bootData.created_at = createdAt;
52      }
53
54      window.Intercom('boot', bootData);
55    };
56
57    return () => {
58      // Cleanup on unmount
59      if (window.Intercom) {
60        window.Intercom('shutdown');
61      }
62      document.head.removeChild(script);
63    };
64  }, [appId, userId, email, name, createdAt]);
65
66  return <>{children}</>;
67}
68
69export function useIntercom() {
70  const showChat = () => window.Intercom?.('show');
71  const hideChat = () => window.Intercom?.('hide');
72  const trackEvent = (eventName: string, metadata?: Record<string, unknown>) => {
73    window.Intercom?.('trackEvent', eventName, metadata);
74  };
75  const updateUser = (attributes: Record<string, unknown>) => {
76    window.Intercom?.('update', attributes);
77  };
78
79  return { showChat, hideChat, trackEvent, updateUser };
80}

Create Next.js API routes for server-side Intercom operations that require your private access token. The most common server-side use cases are: creating or updating contacts when users sign up (to sync user data before they start a chat), logging events when users take key actions (to power Intercom's automation and messaging triggers), and fetching conversations for a custom support inbox. The Intercom REST API base URL is https://api.intercom.io and all requests use your access token in the Authorization header as a Bearer token, plus an Intercom-Version header set to '2.11' (or the current version). Contacts are created via POST /contacts with a role of 'user' and the user's email, external_id, and name. Events are logged via POST /events with the event_name, user_id, created_at (Unix timestamp), and an optional metadata object with additional context. Conversations are fetched via GET /conversations with query parameters for filtering. The Intercom API returns standard HTTP error codes: 401 for invalid access token, 403 for insufficient permissions on a specific resource, 404 for missing resources, and 422 for validation errors on POST requests. Error responses include an errors array with type and message fields that describe the issue clearly. The access token should be stored as INTERCOM_ACCESS_TOKEN in Vercel environment variables without any NEXT_PUBLIC_ prefix — it is a server-only secret.

1// app/api/intercom/events/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const INTERCOM_API = 'https://api.intercom.io';
5const INTERCOM_VERSION = '2.11';
6
7async function intercomRequest(path: string, options: RequestInit = {}) {
8  const token = process.env.INTERCOM_ACCESS_TOKEN;
9  if (!token) throw new Error('INTERCOM_ACCESS_TOKEN is not configured');
10
11  const response = await fetch(`${INTERCOM_API}${path}`, {
12    ...options,
13    headers: {
14      Authorization: `Bearer ${token}`,
15      'Content-Type': 'application/json',
16      Accept: 'application/json',
17      'Intercom-Version': INTERCOM_VERSION,
18      ...((options.headers as Record<string, string>) || {}),
19    },
20  });
21
22  const data = await response.json();
23
24  if (!response.ok) {
25    const message = data?.errors?.[0]?.message || `Intercom API error ${response.status}`;
26    throw new Error(message);
27  }
28
29  return data;
30}
31
32export async function POST(request: NextRequest) {
33  let body: {
34    event_name: string;
35    user_id: string;
36    metadata?: Record<string, string | number | boolean>;
37  };
38
39  try {
40    body = await request.json();
41  } catch {
42    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
43  }
44
45  const { event_name, user_id, metadata } = body;
46
47  if (!event_name || !user_id) {
48    return NextResponse.json(
49      { error: 'event_name and user_id are required' },
50      { status: 400 }
51    );
52  }
53
54  try {
55    await intercomRequest('/events', {
56      method: 'POST',
57      body: JSON.stringify({
58        event_name,
59        user_id,
60        created_at: Math.floor(Date.now() / 1000),
61        metadata: metadata || {},
62      }),
63    });
64
65    return NextResponse.json({ success: true });
66  } catch (error) {
67    const message = error instanceof Error ? error.message : 'Failed to track event';
68    return NextResponse.json({ error: message }, { status: 500 });
69  }
70}

Update your V0-generated components to use Intercom for user identification, event tracking, and triggering the chat widget. Wrap your root layout component with the IntercomProvider, passing the logged-in user's data as props. For apps using Clerk authentication, access the user data in a server component and pass it to the client IntercomProvider. For apps using NextAuth v5, use the auth() function in the layout server component to get session data. The useIntercom hook you created makes it easy to trigger Intercom actions from any component — call trackEvent('button_clicked', { button: 'upgrade' }) when users click key buttons, and showChat() when they click support links. Test locally by adding NEXT_PUBLIC_INTERCOM_APP_ID and INTERCOM_ACCESS_TOKEN to your .env.local file, running npm run dev, and navigating to your app. You should see the Intercom bubble appear in the bottom-right corner immediately. Open the Intercom dashboard to verify that the boot call registered with the correct user data — the user should appear in Intercom's contacts with the attributes you passed. For testing event tracking, trigger an action in your app and check the user's event timeline in Intercom to verify events are arriving correctly. If you're using identity verification (recommended for production), generate the user_hash in a Server Action using the crypto module and the HMAC-SHA256 algorithm with your Intercom Identity Verification secret.

Push your code to GitHub and configure Intercom credentials in Vercel. In the Vercel Dashboard → your project → Settings → Environment Variables, add two variables: NEXT_PUBLIC_INTERCOM_APP_ID with your Intercom App ID (the short public identifier like 'abc12def' — found in Intercom Settings → Installation → Web). This variable needs the NEXT_PUBLIC_ prefix because the Messenger widget is loaded on the client side and needs access to the App ID in browser code. Add INTERCOM_ACCESS_TOKEN with your full access token (a long string — generated in Intercom Settings → Developers → Developer Hub → Your App → Authentication). This variable must NOT have the NEXT_PUBLIC_ prefix because it grants full API access and must stay server-side only. Set both variables for Production, Preview, and Development environments. For NEXT_PUBLIC_INTERCOM_APP_ID, you can safely use the same value in all environments since it is not a secret. For INTERCOM_ACCESS_TOKEN, consider using a different app or token for Preview deployments to avoid test conversations appearing in your production Intercom inbox. After saving, redeploy your project. Test the deployed app by opening it in your browser — the Intercom bubble should appear within a few seconds of page load. Verify in your Intercom dashboard that the deployment URL appears as a source for any test conversations you create. If you need to implement Intercom's identity verification feature for security (preventing users from impersonating others), generate the HMAC-SHA256 hash of the user ID using the INTERCOM_IDENTITY_VERIFICATION_SECRET environment variable in a server action.