Zendesk Ticket Creation

Overview:

Configure and deploy an endpoint that will process the form data.
Call the endpoint from the onSubmit function of your Inkeep widget. Example implementation can be found here

Official Zendesk API Reference

For complete details on available endpoints and ticket parameters, see the official Zendesk Tickets API reference.

This code must be executed in a secure server environment. Never expose your Zendesk API tokens in client-side code as they contain sensitive permissions that could be misused if compromised. Example endpoint for creating a new ticket can be found here

The following example demonstrates how to call the Zendesk Tickets API to create a new ticket. You can copy this code into your project and modify it to suit your needs:

/**
 * Zendesk Ticket Creation Example
 *
 * This example demonstrates how to create a ticket in Zendesk via their REST API.
 *
 * Required environment variables:
 * - ZENDESK_SUBDOMAIN: Your Zendesk subdomain (e.g., 'mycompany' from 'mycompany.zendesk.com')
 * - ZENDESK_EMAIL: Email address for authentication
 * - ZENDESK_API_TOKEN: Zendesk API token
 */
 
// Interface for requester information
export interface RequesterInfo {
  email: string;
  name?: string;
  phone?: string;
  external_id?: string;
  details?: string;
  [key: string]: unknown;
}
 
// Interface for the ticket creation parameters
export interface TicketCreationParams {
  subject: string;
  comment: {
    body: string;
    html_body?: string;
    public?: boolean;
  };
  priority?: "urgent" | "high" | "normal" | "low";
  status?: "new" | "open" | "pending" | "hold" | "solved" | "closed";
  type?: "problem" | "incident" | "question" | "task";
  tags?: string[];
 
  // User and organization information
  requester_id?: number;
  requester?: RequesterInfo;
  submitter_id?: number;
  assignee_id?: number;
  organization_id?: number;
 
  group_id?: number;
  collaborator_ids?: number[];
  collaborators?: Array<string | RequesterInfo>; // Can be emails or objects with name/email
 
  // Additional fields
  custom_fields?: Array<{
    id: number;
    value: string | number | boolean | string[];
  }>;
  due_at?: string; // ISO 8601 format
  via?: {
    channel: string;
    source?: {
      to?: {
        name?: string;
        address?: string;
      };
      from?: {
        name?: string;
        address?: string;
      };
      rel?: string;
    };
  };
  ticket_form_id?: number;
}
 
// Interface for Zendesk API response
export interface ZendeskTicketResponse {
  ticket: {
    id: number;
    subject: string;
    description: string;
    status: string;
    priority: string;
    requester_id?: number;
    organization_id?: number;
    [key: string]: unknown;
  };
  [key: string]: unknown;
}
 
/**
 * Create a ticket in Zendesk
 *
 * @param ticketData - Object containing the ticket information
 * @returns A promise that resolves to the created ticket data
 */
export async function createTicket(
  ticketData: TicketCreationParams
): Promise<ZendeskTicketResponse> {
  // Get environment variables
  const subdomain = process.env.ZENDESK_SUBDOMAIN;
  const email = process.env.ZENDESK_EMAIL;
  const apiToken = process.env.ZENDESK_API_TOKEN;
 
  // Validate environment variables
  if (!subdomain || !email || !apiToken) {
    throw new Error(
      "Missing required environment variables. Please ensure ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, and ZENDESK_API_TOKEN are set."
    );
  }
 
  // Base URL for Zendesk API
  const baseUrl = `https://${subdomain}.zendesk.com/api/v2`;
 
  // Create the ticket payload
  const ticketPayload = {
    ticket: {
      ...ticketData,
    },
  };
 
  try {
    const response = await fetch(`${baseUrl}/tickets.json`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Basic ${btoa(`${email}/token:${apiToken}`)}`,
      },
      body: JSON.stringify(ticketPayload),
    });
 
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Failed to create ticket: ${JSON.stringify(errorData)}`);
    }
 
    return await response.json();
  } catch (error) {
    console.error("Error creating Zendesk ticket:", error);
    throw error;
  }
}
 
// Example usage
async function example() {
  try {
    // First, set your environment variables
    // In a real application, these would be set in your environment
    process.env.ZENDESK_SUBDOMAIN = "your-subdomain";
    process.env.ZENDESK_EMAIL = "your-email@example.com";
    process.env.ZENDESK_API_TOKEN = "your-api-token";
 
    const ticketData: TicketCreationParams = {
      subject: "Support needed with API integration",
      comment: {
        body: "I need help connecting your API with our system. Please assist.",
        public: true,
      },
      // Associate ticket with an existing user by email
      requester: {
        email: "customer@example.com",
        name: "John Customer",
      },
      // Associate with organization
      organization_id: 123456,
      priority: "normal",
      type: "question",
      tags: ["api", "integration", "support"],
      custom_fields: [
        {
          id: 123456, // Replace with actual custom field ID
          value: "Some custom value",
        },
      ],
    };
 
    // Create a ticket
    const result = await createTicket(ticketData);
    console.log("Ticket created successfully:", result);
  } catch (error) {
    console.error("Error in example:", error);
  }
}

Prefill a Zendesk ticket form

Alternatively, you can use the callback function to prefill a Zendesk ticket form with the user's questions. See the Zendesk documentation for more details on how to create a pre-filled ticket form.

Example:

const aiChatSettings: InkeepAIChatSettings = {
  // ...
  getHelpOptions: [
     {
      icon: { builtIn: 'IoHelpBuoyOutline' },
      name: 'Create a support ticket',
      action: {
        type: 'invoke_callback',
        callback: ({ conversation }) => {
          try {
            const { messages, userProperties } = conversation
            // List the user's questions
            const description = messages.length > 0 ?
            "Here's what I need help with:\n\n" +
            messages
              .filter((message) => message.role === "user")
              .map((message) => message.content)
              .join("\n") : ''
    
            const userEmail = String(userProperties?.['email'] || '')
            const params = new URLSearchParams()
            params.set('ticket_form_id', 'REPLACE_WITH_YOUR_FORM_ID') // if you have multiple forms pass the form id here, otherwise omit
            params.set('tf_description', description) // prefill the description field with the user's questions
            params.set('tf_subject', 'Support request') // prefill the subject field with a default subject
            params.set('tf_REPLACE_WITH_YOUR_USER_EMAIL_FIELD_ID', userEmail) // if you know the user's email, you can pass it here
            const url = `https://REPLACE_WITH_YOUR_SUBDOMAIN.zendesk.com/hc/en-us/requests/new?${params.toString()}`
            window.open(url, '_blank')
          } catch (error) {
            console.error('Error opening support form', error)
          }
        },
      },
    },
  ],
};

Zendesk Ticket Creation

Overview:

Official Zendesk API Reference

Basic Ticket Creation

Prefill a Zendesk ticket form

On this page