How to Integrate Bolt.new with Freshdesk

Freshdesk provides a personal API key for each agent. Log into your Freshdesk account, click your profile picture in the top-right corner, and select 'Profile Settings'. On your profile page, scroll to the 'API Key' section on the right side. Your API key is displayed here — it's a 20+ character alphanumeric string. Click the eye icon to reveal it if it's hidden, then copy it. If you don't see an API key section, your plan may not include API access, or you may need to enable it in the Admin settings. Your Freshdesk domain is the subdomain you use to access your account — if you go to https://yourcompany.freshdesk.com, then 'yourcompany' is your domain. Store your API key as a server-side environment variable (no NEXT_PUBLIC_ prefix). Freshdesk API calls use HTTP Basic Auth where the username is your API key and the password is the literal letter 'X' — this unusual convention is specific to Freshdesk and is documented in their API reference. Never expose your API key in client-side code — it gives anyone read and write access to all your tickets and customer data.

1# .env
2FRESHDESK_API_KEY=your_api_key_here
3FRESHDESK_DOMAIN=yourcompany

Build a reusable helper that handles Freshdesk API calls with proper authentication. The helper accepts an endpoint path and request options, adds the Base64-encoded Basic Auth header, and returns the response JSON. Centralizing this logic means all API routes share the same auth pattern and you only need to change credentials in one place. Freshdesk's API base URL is https://{domain}.freshdesk.com/api/v2/. Common endpoints are /tickets (create and list tickets), /contacts (manage contact records), /solution/articles (knowledge base articles), and /agents (list agents for assignment). For Basic Auth with Freshdesk, encode 'API_KEY:X' in Base64. The colon and 'X' are always part of the encoding — Freshdesk ignores the password field and only validates the API key. Error responses from Freshdesk's API are returned as JSON with a 'description' field and an 'errors' array. Parse these carefully since Freshdesk returns different error formats depending on the type of validation failure.

1// lib/freshdesk.ts
2const FRESHDESK_BASE = `https://${process.env.FRESHDESK_DOMAIN}.freshdesk.com/api/v2`;
3
4function getFreshdeskHeaders() {
5  const auth = Buffer.from(`${process.env.FRESHDESK_API_KEY}:X`).toString('base64');
6  return {
7    Authorization: `Basic ${auth}`,
8    'Content-Type': 'application/json',
9    Accept: 'application/json',
10  };
11}
12
13export async function freshdeskAPI<T>(
14  endpoint: string,
15  options: RequestInit = {}
16): Promise<T> {
17  const url = `${FRESHDESK_BASE}${endpoint}`;
18  const response = await fetch(url, {
19    ...options,
20    headers: {
21      ...getFreshdeskHeaders(),
22      ...options.headers,
23    },
24  });
25
26  if (!response.ok) {
27    const error = await response.json().catch(() => ({ description: response.statusText }));
28    throw new Error(
29      error.description || `Freshdesk API error: ${response.status}`
30    );
31  }
32
33  // 204 No Content for DELETE operations
34  if (response.status === 204) return {} as T;
35
36  return response.json();
37}

The most common Freshdesk integration for Bolt apps is a contact form that creates support tickets. When a user submits a help request, your API route receives the form data and creates a Freshdesk ticket via the API. Freshdesk tickets require at minimum a subject, description, email (requester), and status (2 = open). Priority is optional but recommended: 1 = low, 2 = medium, 3 = high, 4 = urgent. When you create a ticket, Freshdesk automatically sends a confirmation email to the requester with the ticket number — this is one of the biggest benefits of using Freshdesk over a simple email form. You can also assign the ticket to a specific agent or group by including the responder_id or group_id fields. Tag tickets with custom labels (the tags array) to categorize them — for example, tagging tickets from your Bolt app as 'bolt-app' helps filter them from manually created tickets in the Freshdesk inbox. Always validate user input before sending to Freshdesk — empty subjects, invalid emails, or descriptions over 65,535 characters will result in 400 errors from the API.

1// app/api/freshdesk/tickets/route.ts
2import { NextResponse } from 'next/server';
3import { freshdeskAPI } from '@/lib/freshdesk';
4
5interface FreshdeskTicket {
6  id: number;
7  subject: string;
8  description: string;
9  status: number;
10  priority: number;
11  requester_id: number;
12  created_at: string;
13}
14
15export async function POST(request: Request) {
16  try {
17    const { subject, description, email, priority = 2 } = await request.json();
18
19    if (!subject || !description || !email) {
20      return NextResponse.json(
21        { error: 'subject, description, and email are required' },
22        { status: 400 }
23      );
24    }
25
26    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
27      return NextResponse.json(
28        { error: 'Invalid email address' },
29        { status: 400 }
30      );
31    }
32
33    const ticket = await freshdeskAPI<FreshdeskTicket>('/tickets', {
34      method: 'POST',
35      body: JSON.stringify({
36        subject,
37        description,
38        email,
39        priority,
40        status: 2, // Open
41        source: 2, // Portal
42        tags: ['bolt-app'],
43      }),
44    });
45
46    return NextResponse.json(
47      { ticketId: ticket.id, message: 'Ticket created successfully' },
48      { status: 201 }
49    );
50  } catch (error: unknown) {
51    const e = error as { message: string };
52    return NextResponse.json({ error: e.message }, { status: 500 });
53  }
54}
55
56export async function GET(request: Request) {
57  try {
58    const { searchParams } = new URL(request.url);
59    const status = searchParams.get('status') || '2';
60    const page = searchParams.get('page') || '1';
61
62    const tickets = await freshdeskAPI<FreshdeskTicket[]>(
63      `/tickets?status=${status}&per_page=50&page=${page}&order_by=created_at&order_type=desc`
64    );
65
66    return NextResponse.json(tickets);
67  } catch (error: unknown) {
68    const e = error as { message: string };
69    return NextResponse.json({ error: e.message }, { status: 500 });
70  }
71}

Complete the integration by building an admin ticket dashboard and a knowledge base search feature. The ticket dashboard queries the Freshdesk API for open tickets and displays them with status indicators, priority colors, and requester information. Agents can update ticket status directly from the dashboard using a PATCH request to Freshdesk's API. For knowledge base search, Freshdesk's Solutions API provides access to all your help articles by category and folder. The search endpoint (/search/solutions?term=query) returns matching articles with their titles and content previews. Display these in a dropdown or slide-over panel to help users self-serve before submitting a ticket. Remember that all Freshdesk API calls (both reads and writes) work from Bolt's WebContainer preview because they're outbound HTTPS calls — you don't need to deploy to test the full ticket creation and dashboard flow. Freshdesk's rate limit is 1,000 API calls per hour per account on most plans, and 10,000 on Enterprise. This is generous for dashboard use but be careful with bulk operations like importing many tickets.

1// app/api/freshdesk/search/route.ts
2import { NextResponse } from 'next/server';
3import { freshdeskAPI } from '@/lib/freshdesk';
4
5interface SolutionArticle {
6  id: number;
7  title: string;
8  description_text: string;
9  folder_id: number;
10}
11
12interface SearchResult {
13  results: SolutionArticle[];
14  total: number;
15}
16
17export async function GET(request: Request) {
18  const { searchParams } = new URL(request.url);
19  const query = searchParams.get('q');
20
21  if (!query || query.trim().length < 2) {
22    return NextResponse.json({ results: [] });
23  }
24
25  try {
26    const data = await freshdeskAPI<SearchResult>(
27      `/search/solutions?term=${encodeURIComponent(query)}`
28    );
29    return NextResponse.json(data);
30  } catch (error: unknown) {
31    const e = error as { message: string };
32    return NextResponse.json({ error: e.message }, { status: 500 });
33  }
34}