How to Integrate Bolt.new with Zendesk

Log in to your Zendesk account and navigate to the Admin Center. You can find Admin Center at the bottom of the left sidebar (the gear icon) or directly at https://your-subdomain.zendesk.com/admin. In Admin Center, go to Apps and Integrations → APIs → Zendesk API. On the Settings tab, enable the Token Access toggle if it's not already on. Click Add API token, optionally add a description, and click Create. The token is displayed once — copy it. If you navigate away before copying, you'll need to create a new token. Zendesk's API uses HTTP Basic authentication. The username is your agent email address followed by /token (literally the string '/token', not a token value). The password is your API token. When combined with Base64 encoding for the Authorization header, the format is: Authorization: Basic base64(email/token:api_token). In Node.js, use Buffer.from('email@example.com/token:your_api_token').toString('base64'). In your Bolt project, store three values in .env.local: ZENDESK_SUBDOMAIN (e.g., 'mycompany'), ZENDESK_EMAIL (your agent email), and ZENDESK_API_TOKEN (the token you copied). The subdomain and email are not strictly secret but treat them as server-side variables anyway to keep your configuration consistent. The API token must be server-side only — it grants full API access to your Zendesk account. For the Web Widget (step 4), you also need NEXT_PUBLIC_ZENDESK_KEY which is a public key safe to expose in client-side code — it's different from the API token and only controls which Zendesk account the widget connects to.

1// .env.local
2ZENDESK_SUBDOMAIN=your_subdomain_here
3ZENDESK_EMAIL=your_agent_email@company.com
4ZENDESK_API_TOKEN=your_api_token_here
5# Public key for Web Widget (safe to expose in client code)
6NEXT_PUBLIC_ZENDESK_KEY=your_zendesk_widget_key
7
8// lib/zendesk.ts
9export function getZendeskAuth(): string {
10  const email = process.env.ZENDESK_EMAIL!;
11  const token = process.env.ZENDESK_API_TOKEN!;
12  return Buffer.from(`${email}/token:${token}`).toString('base64');
13}
14
15export async function zendeskFetch(
16  endpoint: string,
17  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' = 'GET',
18  body?: Record<string, unknown>
19): Promise<Response> {
20  const subdomain = process.env.ZENDESK_SUBDOMAIN!;
21  const url = `https://${subdomain}.zendesk.com/api/v2${endpoint}`;
22
23  return fetch(url, {
24    method,
25    headers: {
26      Authorization: `Basic ${getZendeskAuth()}`,
27      'Content-Type': 'application/json',
28      Accept: 'application/json',
29    },
30    ...(body ? { body: JSON.stringify(body) } : {}),
31  });
32}

The Zendesk Tickets API creates tickets via POST /api/v2/tickets.json with a ticket object in the request body. The minimum required fields are subject and a comment object with a body string. The requester field (email and name) identifies who submitted the ticket — if a user with that email already exists in Zendesk, the ticket is linked to their account. If not, Zendesk creates a new end-user record automatically. Useful optional fields for ticket creation: priority (urgent, high, normal, low), type (question, incident, problem, task), tags (array of strings for categorization and routing), assignee_id (Zendesk agent ID to assign the ticket to), and group_id (support team/group to assign it to). For contact forms from your Bolt app, setting a tag like 'bolt-contact-form' is valuable for filtering tickets by source in Zendesk. The API response returns the created ticket with its id (numeric), status (new), url, and all other fields. The ticket id is what you display to the user as their reference number. You can also use it to link subsequent comments or status checks to the original ticket. For attachments (like screenshots or files the user uploads with their ticket), use Zendesk's two-step upload process: POST to /api/v2/uploads.json to upload the file and get a token, then include the token in the ticket creation request under comment.uploads. This is optional — most contact forms work fine with text-only ticket creation. All these operations are outbound POST and GET requests to Zendesk's API — they work from Bolt's WebContainer without any deployment required.

1// app/api/zendesk/tickets/create/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { zendeskFetch } from '@/lib/zendesk';
4
5export async function POST(request: NextRequest) {
6  const {
7    requesterName,
8    requesterEmail,
9    subject,
10    message,
11    priority = 'normal',
12  } = await request.json();
13
14  if (!requesterEmail || !subject || !message) {
15    return NextResponse.json(
16      { error: 'requesterEmail, subject, and message are required' },
17      { status: 400 }
18    );
19  }
20
21  const body = {
22    ticket: {
23      subject,
24      comment: { body: message },
25      requester: {
26        name: requesterName ?? requesterEmail,
27        email: requesterEmail,
28      },
29      priority,
30      tags: ['bolt-contact-form'],
31      via: {
32        channel: 'web_widget',
33      },
34    },
35  };
36
37  const response = await zendeskFetch('/tickets.json', 'POST', body);
38
39  if (!response.ok) {
40    const error = await response.json();
41    return NextResponse.json({ error }, { status: response.status });
42  }
43
44  const data = await response.json();
45  const ticket = data.ticket;
46
47  return NextResponse.json({
48    ticketId: ticket.id,
49    status: ticket.status,
50    subject: ticket.subject,
51    createdAt: ticket.created_at,
52    url: ticket.url,
53  });
54}

The Zendesk Tickets API supports powerful filtering for building dashboards. The main listing endpoint is GET /api/v2/tickets.json with filter parameters. To get tickets by status: GET /api/v2/tickets.json?status=open returns all open tickets. Combining multiple filters uses the Zendesk Search API: GET /api/v2/search.json?query=type:ticket+status:open+priority:urgent returns high-priority open tickets. The search API is the most flexible tool for building dashboards: it supports sorting (sort_by=created_at&sort_order=desc), filtering by date range (created>2024-01-01), assignee (assignee:me), group, and any ticket field. The query syntax is documented at developer.zendesk.com/api-reference/ticketing/ticket-management/search/. Each ticket object in the response includes id, subject, status, priority, requester_id, assignee_id, created_at, updated_at, and tags. To display the requester's email and name, you'll need to fetch user details using GET /api/v2/users/{userId}.json or use the sideload feature: appending ?include=users to the tickets endpoint fetches user data in the same request, avoiding N+1 queries. For the dashboard UI, Bolt can generate a data table component with sortable columns, status badge pills, priority color coding, and a link to the Zendesk ticket. Describe the layout in a Bolt chat prompt and it will scaffold the React component that consumes your /api/zendesk/tickets route.

1// app/api/zendesk/tickets/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { zendeskFetch } from '@/lib/zendesk';
4
5export async function GET(request: NextRequest) {
6  const { searchParams } = new URL(request.url);
7  const status = searchParams.get('status') ?? 'open';
8  const perPage = searchParams.get('per_page') ?? '25';
9
10  // Use Search API for flexible filtering with user sideloading
11  const query = `type:ticket status:${status}`;
12  const params = new URLSearchParams({
13    query,
14    sort_by: 'created_at',
15    sort_order: 'desc',
16    per_page: perPage,
17    include: 'users',
18  });
19
20  const response = await zendeskFetch(`/search.json?${params}`);
21
22  if (!response.ok) {
23    return NextResponse.json({ error: 'Zendesk API error' }, { status: response.status });
24  }
25
26  const data = await response.json();
27  const usersMap = new Map(
28    (data.users ?? []).map((u: Record<string, unknown>) => [u.id, u])
29  );
30
31  const tickets = (data.results ?? []).map((t: Record<string, unknown>) => {
32    const requester = usersMap.get(t.requester_id) as Record<string, unknown> | undefined;
33    return {
34      id: t.id,
35      subject: t.subject,
36      status: t.status,
37      priority: t.priority ?? 'normal',
38      requesterName: requester?.name ?? 'Unknown',
39      requesterEmail: requester?.email ?? '',
40      createdAt: t.created_at,
41      updatedAt: t.updated_at,
42      tags: t.tags ?? [],
43    };
44  });
45
46  return NextResponse.json({ tickets, total: data.count });
47}

The Zendesk Web Widget is the fastest way to add live chat support to your Bolt app. Unlike the REST API integration which requires server routes and authentication, the Web Widget is a client-side JavaScript snippet that loads Zendesk's own chat interface. You add one script tag to your layout and users get a professionally designed chat button with live chat, ticket submission, and knowledge base search. To get your Widget key, go to Zendesk Admin Center → Channels → Classic → Widget. The Widget key (sometimes called the web widget key) is displayed on this page — it looks like a UUID. This is a public key safe to expose in client-side code — store it as NEXT_PUBLIC_ZENDESK_KEY in your .env.local. In Next.js App Router, load the Widget in a client component to avoid SSR issues (the script accesses window and document). Create a component that uses useEffect to append the Zendesk script to the document head. Load the component in your root layout so it appears on all pages. You can customize the Widget's appearance, default tab (chat vs. help center vs. contact form), and pre-fill fields with known user data using the window.zE API. For logged-in users, pre-fill the name and email fields so they don't have to type them when opening a support chat. This is done by calling window.zE('webWidget', 'identify', { name, email }) after the Widget loads. The Web Widget script loads asynchronously from Zendesk's CDN and renders in the browser — it works immediately in Bolt's WebContainer preview. You can test the full chat experience including connecting to your Zendesk agent workspace without deploying.

1// components/ZendeskWidget.tsx
2'use client';
3
4import { useEffect } from 'react';
5
6declare global {
7  interface Window {
8    zE?: (...args: unknown[]) => void;
9    zESettings?: Record<string, unknown>;
10  }
11}
12
13export function ZendeskWidget() {
14  useEffect(() => {
15    const key = process.env.NEXT_PUBLIC_ZENDESK_KEY;
16    if (!key || document.getElementById('ze-snippet')) return;
17
18    // Configure widget before loading
19    window.zESettings = {
20      webWidget: {
21        chat: { suppress: false },
22        contactForm: { suppress: false },
23        helpCenter: { suppress: false },
24        launcher: { chatLabel: { 'en-US': 'Chat with us' } },
25        color: { theme: '#0073e6' },
26      },
27    };
28
29    const script = document.createElement('script');
30    script.id = 'ze-snippet';
31    script.src = `https://static.zdassets.com/ekr/snippet.js?key=${key}`;
32    script.async = true;
33    document.head.appendChild(script);
34
35    return () => {
36      const existing = document.getElementById('ze-snippet');
37      if (existing) existing.remove();
38    };
39  }, []);
40
41  return null;
42}
43
44// app/layout.tsx — add to your existing layout:
45// import { ZendeskWidget } from '@/components/ZendeskWidget';
46// Inside <body>:
47// <ZendeskWidget />

Zendesk's webhook system sends HTTP notifications to your app when tickets are created, updated, or when specific trigger conditions are met. This is useful for syncing ticket data to your own database, posting ticket updates to Slack or Teams, or triggering automated workflows when a ticket reaches a certain status. Like all incoming HTTP connections, Zendesk webhook calls cannot reach Bolt's WebContainer. The WebContainer runs inside a browser tab without a public URL. Deploy your app to Netlify or Vercel first, then create the webhook target in Zendesk. Create a Zendesk webhook target: go to Admin Center → Apps and Integrations → Webhooks → Create webhook. Set the endpoint URL to your deployed route (e.g., https://your-app.netlify.app/api/zendesk/webhook), method to POST, request format to JSON. Add a request signing secret — Zendesk will include a signature header you can use to verify the request is genuine. Click Create webhook. Webhooks alone don't fire automatically — you need a Zendesk Trigger to link events to the webhook. Go to Admin Center → Business Rules → Triggers → Add trigger. Set conditions (e.g., 'Ticket is created' or 'Ticket status changed to Solved') and add a notification action: Notify active webhook → select your webhook → configure the JSON payload. The trigger fires whenever its conditions are met, sending the configured payload to your webhook URL. Add your Zendesk webhook signing secret to your hosting platform's environment variables as ZENDESK_WEBHOOK_SECRET before enabling the webhook.

1// app/api/zendesk/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import crypto from 'crypto';
4
5export async function POST(request: NextRequest) {
6  const rawBody = await request.text();
7  const secret = process.env.ZENDESK_WEBHOOK_SECRET;
8
9  if (secret) {
10    const timestamp = request.headers.get('X-Zendesk-Webhook-Request-Timestamp') ?? '';
11    const webhookId = request.headers.get('X-Zendesk-Webhook-Id') ?? '';
12    const signature = request.headers.get('X-Zendesk-Webhook-Signature') ?? '';
13
14    const toSign = timestamp + webhookId + rawBody;
15    const expected = crypto
16      .createHmac('sha256', secret)
17      .update(toSign)
18      .digest('base64');
19
20    if (signature !== expected) {
21      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
22    }
23  }
24
25  let payload: Record<string, unknown>;
26  try {
27    payload = JSON.parse(rawBody);
28  } catch {
29    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 });
30  }
31
32  // Process the ticket event
33  const ticketId = payload.ticket_id ?? payload.id;
34  const status = payload.status ?? payload.ticket_status;
35  const subject = payload.subject ?? payload.ticket_subject;
36
37  console.log(`Zendesk ticket event: ID=${ticketId}, status=${status}, subject=${subject}`);
38
39  // Add your business logic here:
40  // - Update your database
41  // - Send a Slack/Teams notification
42  // - Trigger a workflow
43
44  return NextResponse.json({ received: true });
45}