Zendesk Integration Documentation

Overview

The Zendesk integration in Vantage allows users to interface with Zendesk's ticketing system using the Zendesk REST API. This integration enables the retrieval, management, and analysis of support tickets directly within the Vantage platform. Through this integration, users can view ticket statuses, counts, and specifics, which aids in better support management and response strategies.

Purpose

• To connect Vantage with Zendesk's API and facilitate the access and manipulation of support ticket data.
• To streamline the support management process by allowing for automated data retrieval and reporting.
• To provide actionable insights based on ticket data directly in the Vantage environment.

Settings

The Zendesk integration has the following settings:

1. Subdomain

• Type: String
• Description: This setting specifies the Zendesk subdomain where your Zendesk account is hosted. The subdomain is required to construct the base URL for API calls.
• Default Value: None (This is a required field and must be provided).

2. Email

• Type: String
• Description: This field takes the email address associated with your Zendesk account. It will be used in combination with the API token to create authenticated requests to the Zendesk API.
• Default Value: None (This is a required field and must be provided).

3. API Token

• Type: String
• Description: This is a unique token used to authorize and authenticate requests made to the Zendesk API. The API token ensures that the requests are securely made over HTTPS.
• Default Value: None (This is a required field and must be provided).

4. Request Initialization

• Type: Object (optional)
• Description: This optional setting allows users to customize the request initializations, including additional headers or specific configuration for the requests made to the Zendesk API. You can enhance request specificity by including any necessary authentication keys or custom headers.
• Default Value: {} (An empty object, meaning no additional headers are added by default).

5. Status (in listTickets and countTickets methods)

• Type: String
• Description: This input setting allows users to filter tickets based on their status, e.g., "open", "pending", "solved", etc. Changing this affects the results retrieved and allows users to focus on specific ticket types as per operational needs.
• Default Value: "open" (If not specified, the integration will retrieve only open tickets).

6. Per Page (in listTickets method)

• Type: Numeric
• Description: This setting specifies how many tickets to return per request (pagination). Modifying it changes the number of tickets shown in the response and can help in managing large datasets in smaller chunks.
• Default Value: 5 (If not provided, the integration defaults to returning five tickets).

How It Works

The integration works by establishing a connection to the Zendesk API using user-provided credentials (subdomain, email, and API token):

1. Authentication: The authorize method encodes the email and token in base64 for secure communication with Zendesk's API.
2. Connection Testing: The testConnection method verifies that the credentials work by fetching the ticket count.
3. Data Retrieval: The listTickets method retrieves a specified number of tickets based on the chosen status, while the countTickets method provides the total count of tickets based on specified parameters.

Expected Data

The integration requires:

• A valid Zendesk subdomain
• An active email and API token combination to authenticate requests
• The ability to specify options for filtering tickets by status and pagination limits

Use Cases & Examples

Use Case 1: Support Ticket Monitoring

A customer support manager wants to monitor the status of tickets regularly to ensure timely responses. Using this integration, they can automatically retrieve counts and lists of open tickets and filter them based on urgency.

Use Case 2: Reporting on Ticket Volume

A business analyst needs a report detailing ticket volume over a specific period. By utilizing the countTickets method and adjusting the status parameters, they can collect data for analysis and present findings to stakeholders.

Configuration Example

Scenario: A customer service team wants to retrieve a list of open support tickets, capped at ten tickets per request.

Sample Configuration Data:

const zendeskIntegration = new Zendesk({
  subdomain: 'mycompany',
  email: 'support@mycompany.com',
  apiToken: 'your-api-token-here',
});

// Fetching open tickets
const openTickets = await zendeskIntegration.listTickets({
  status: 'open',
  per_page: 10
});

In this example, the integration is configured with the required credentials. The listTickets method is called to fetch ten open tickets, which will help the support team stay informed and responsive to customer issues effectively.