Zendesk Ticket Creation

/**
 * 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);
  }
}