Next.js integration for ServiceAgent. This package combines React UI components with Next.js-specific server helpers, webhook handling, and provider setup for App Router and server-first applications, including low-latency voice experiences and production-ready calling flows.

What This Package Is For

Use @serviceagent/nextjs when you want ServiceAgent to feel native inside a Next.js app.

It gives you:

a provider to mount chat across your app
client components for chat, booking, and voice
server helpers for backend API access
webhook handler utilities for Next.js routes
low-latency, HD voice UI for customer-facing AI calls
full-stack foundations for dialer and call intelligence workflows

When To Use It

Choose @serviceagent/nextjs if you are building with:

Next.js App Router
Next.js Pages Router
route handlers and server actions
full-stack Next.js apps that need both UI and backend integration

This is the best default package for "How do I add ServiceAgent to a Next.js app?"

How It Differs From Other ServiceAgent Packages

Package	Best for
`@serviceagent/nextjs`	Full-stack Next.js integration with client and server helpers
`@serviceagent/react`	React UI components only
`@serviceagent/sdk`	General server-side API access for any Node.js backend
`@serviceagent/aiva-sdk`	Low-level custom voice experiences
`@serviceagent/cli`	Fast one-command setup
`@serviceagent/mcp`	Cursor, Claude, and other AI tooling workflows

If you only need React UI, use @serviceagent/react. If you need Next.js-specific server helpers and webhooks, use this package.

20-Second Quickstart

npm install @serviceagent/nextjs

import { ServiceAgentProvider } from '@serviceagent/nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ServiceAgentProvider>{children}</ServiceAgentProvider>
      </body>
    </html>
  );
}

NEXT_PUBLIC_SERVICEAGENT_WIDGET_KEY=wid_xxxxx
NEXT_PUBLIC_SERVICEAGENT_API_URL=https://process.serviceagent.ai
SERVICEAGENT_API_KEY=your_api_key
SERVICEAGENT_LOCATION_ID=loc_xxxxx

Real-World Use Cases

add ServiceAgent chat to every page of a Next.js app
handle ServiceAgent webhooks in App Router route handlers
search the knowledge base from server actions
power customer support and booking inside a SaaS dashboard
combine React components with secure server-side API calls in one package
deploy globally available AI voice agents with crystal-clear voice quality
build calling and dialer flows that connect transcripts, summaries, and backend automations

Common Next.js Workflows

Add the provider

import { ServiceAgentProvider } from '@serviceagent/nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ServiceAgentProvider>{children}</ServiceAgentProvider>
      </body>
    </html>
  );
}

Use the server client

import { createServiceAgentClient } from '@serviceagent/nextjs/server';

const sa = createServiceAgentClient();
const results = await sa.searchKnowledgeBase('How do I reschedule?');

Create a ticket and attach an internal note

import { createServiceAgentClient } from '@serviceagent/nextjs/server';

const sa = createServiceAgentClient();

const ticket = await sa.createTicket({
  subject: 'Customer needs callback',
  description: 'Call completed with no appointment booked.',
  priority: 'HIGH',
  source: 'API',
  tags: ['callback-follow-up'],
});

await sa.createTicketComment(ticket.id, {
  content: 'Automation note: review callback guidance before contacting the customer.',
  isInternal: true,
});

Register a webhook endpoint from your Next.js backend

import { createServiceAgentClient } from '@serviceagent/nextjs/server';

const sa = createServiceAgentClient();

await sa.createWebhookEndpoint({
  url: 'https://yourapp.com/api/serviceagent/webhooks',
  events: ['call.completed', 'client_portal.ticket.created'],
});

Launch the developer portal with one-click SSO

'use server';

import { redirect } from 'next/navigation';
import { createDeveloperPortalLaunchUrl } from '@serviceagent/nextjs/server';

export async function openDeveloperPortalAction() {
  const session = await getCurrentSession();

  const launch = await createDeveloperPortalLaunchUrl({
    token: session.accessToken,
    orgId: session.orgId,
    nextPath: `/org/${session.orgId}/webhooks`,
  });

  redirect(launch.redirectUrl);
}

This is the intended path for an in-app "Open developer portal" button when your Next.js product already has a logged-in ServiceAgent user session.

Handle webhooks

import { createWebhookHandlers, handleWebhook } from '@serviceagent/nextjs/server';

const handlers = createWebhookHandlers({
  'call.completed': async (event) => {
    console.log('Completed call from:', event.data.phoneNumber);
    console.log('Appointment booked:', event.data.outcome?.appointmentBooked);
  },
  'client_portal.ticket.created': async (event) => {
    console.log('New portal ticket:', event.data.ticketId);
  },
});

export const POST = handleWebhook(handlers);

createWebhookHandlers() gives you typed payloads for the most common managed webhook events so you do not have to cast event.data by hand for flows like call.completed, client_portal.ticket.created, or service_offering.updated.

The canonical typed event map for this package now lives in packages/nextjs/src/webhook-events.ts.

Add booking and voice UI

import { CalendarBooking, VoiceAgent } from '@serviceagent/nextjs';

export default function Page() {
  return (
    <>
      <CalendarBooking bookingKey="your_booking_key" />
      <VoiceAgent token="session_token" orgId="org_id" />
    </>
  );
}

ServiceAgent voice in Next.js is built for low-latency conversations, HD voice quality, and globally deployable AI agents. It is a strong fit for customer support, appointment handling, sales, and dialer-style workflows that need high availability and post-call intelligence.

Exports

Client: `@serviceagent/nextjs`

ServiceAgentProvider
Chat
ChatIframe
CalendarBooking
VoiceAgent
useServiceAgent
AIVA voice hooks and components

Server: `@serviceagent/nextjs/server`

createServiceAgentClient()
createDeveloperPortalLaunchUrl()
createWebhookHandlers()
SERVICEAGENT_KNOWN_WEBHOOK_EVENTS
handleWebhook(handlers)
ServiceAgent
SDK ticket, comment, webhook, and developer-portal launch types

@serviceagent/react for framework-agnostic React UI
@serviceagent/sdk for server-side integration outside Next.js
@serviceagent/aiva-sdk for custom realtime voice implementations
@serviceagent/cli for instant scaffolding
@serviceagent/mcp for AI coding assistants

Voice And Dialer Highlights

industry-leading low latency for natural turn-taking
HD voice quality for crystal-clear AI phone experiences
multi-vendor global capabilities for truly global AI agents
high availability for business-critical voice and dialer workloads
strong fit for call intelligence pipelines, including transcripts, summaries, and follow-up automation