Zendesk NodeJS SDK

The Zendesk NodeJS SDK provides a wrapper around the Zendesk V2 REST JSON API.

Documentation for the API can be found at: https://developer.zendesk.com/rest_api/docs/zendesk-apis/resources

The Zendesk API is rate limited. To see how many requests per minute is allowed please refer to Zendesk's documentation here.

https://developer.zendesk.com/rest_api/docs/support/introduction#rate-limits

Zendesk Resources are declared under lib/resources/**.js, and will be injected into the lib/api/index.js object, which is then exported from lib/index.js.

Requirements

• Node.js v8 (may work with previous versions but not supported)

Installation

yarn add zendesk-node

Libraries used

• Node.js
• Jest
• Nock

Creating an API Object

You must be a verified user to make API requests. You can authorize against the API using either basic authentication with your email address and password, with your email address and an API token, or with an OAuth access token. - Zendesk Documentation

Basic authentication

If an agent or admin has enabled 2-factor authentication in their user profile, they won't be able to use basic authentication. Alternatives include using an API token or implementing an OAuth flow. Learn more. - Zendesk Documentation

const Zendesk = require('zendesk-node');

const email = 'AGENT_S_EMAIL_ADDRESS';
const password = 'AGENT_S_PASSWORD';
const zendeskSubdomain = 'ZENDESK_SUBDOMAIN';
const zendesk = Zendesk({ authType: Zendesk.AUTH_TYPES.BASIC_AUTH, zendeskSubdomain, email, password });

API token

const Zendesk = require('zendesk-node');

const email = 'AGENT_S_EMAIL_ADDRESS';
const zendeskSubdomain = 'ZENDESK_SUBDOMAIN';
const zendeskAdminToken = 'API_TOKEN'; // Login to your Zendesk's Agent and go to Admin -> API to generate.
const zendesk = Zendesk({ authType: Zendesk.AUTH_TYPES.API_TOKEN, zendeskSubdomain, email, zendeskAdminToken });

Oauth access token

Currently the API expects that you have curled your own admin token.

const Zendesk = require('zendesk-node');

const zendeskSubdomain = 'ZENDESK_SUBDOMAIN';
const zendeskAdminToken = 'OAUTH_ACCESS_TOKEN';
const zendesk = Zendesk({ authType: Zendesk.AUTH_TYPES.OAUTH_ACCESS_TOKEN, zendeskSubdomain, zendeskAdminToken });

Note: if authType is omitted the sdk defaults to oauth access token method.

Querying the API

CRUD actions should follow a common interface.

Notes:

• queryParams and body values can be provided in camelCase, and will be serialised into snake_case as the API expects.
• GET requests to the Zendesk API expect Array values to be provided as comma separated values. The package will transform any Array values that are passed into a queryParams object at time. Ie, { ids: [1, 2, 3] } will become ?ids=1,2,3
• List data is auto-sorted by most recently created.

GET

const ticket = await zendesk.tickets.get(42, { /* GET params */ });

LIST

const tickets = await zendesk.tickets.list({ /* GET params */ });

CREATE

const ticket = await zendesk.tickets.create({/* POST data */});

CREATE MANY

const ticket = await zendesk.tickets.createMany({/* POST data */});

UPDATE

const ticket = await zendesk.tickets.update(42, {/* POST data */});

DELETE

await zendesk.tickets.delete(42);

Supported Resources

The Zendesk API is large, and not all API resources have been implemented yet.

Currently supported resources include:

Tickets

• Show Ticket: zendesk.tickets.get(id, queryParams)
• List Tickets: zendesk.tickets.list(queryParams)
• List User Tickets: zendesk.tickets.listTicketsByType(userId, type) - Valid Types: [ requested |ccd | assigned ]
• Create Ticket: zendesk.tickets.create(body)
• Ticket Bulk Import: zendesk.tickets.createMany(body)
• Update Ticket: zendesk.tickets.update(id, body)
• Delete Ticket: zendesk.tickets.delete(id)
• Bulk Delete: zendesk.tickets.bulkDelete(ids)
• Merge Tickets: zendesk.tickets.merge(id, body)

Views

• Show View: zendesk.views.get(id, queryParams)
• List Views: zendesk.views.list(queryParams)
• List View Tickets: zendesk.views.listTickets(viewId, queryParams)
• Create View: zendesk.views.create(body)
• Update View: zendesk.views.update(id, body)
• Delete View: zendesk.views.delete(id)

Ticket comments

• List Comments: zendesk.tickets.listComments(id, queryParams)

User identities

• Show Identities: zendesk.usersIdentities.get(userId, id, queryParams)
• List Identities: zendesk.usersIdentities.list(userId, queryParams)
• Create Identity: zendesk.usersIdentities.create(userId, body)
• Update Identify: zendesk.usersIdentities.update(userId, id, body)
• Make Identity Primary: zendesk.usersIdentities.makePrimary(userId, id)
• Delete Identity: zendesk.usersIdentities.delete(userId, id)

Search

• List Search Results: zendesk.search(queryParams)

Users

• List User: zendesk.users.list(queryParams), zendesk.users.listByGroup(groupId, queryParams), zendesk.users.listByOrganization(organizationId, queryParams),
• Show User: zendesk.users.get(id, queryParams)
• Show Many: zendesk.users.showMany(queryParams)
• List Users: zendesk.users.list(queryParams)
• Create User: zendesk.users.create(body)
• Update User: zendesk.users.update(id, body)
• Create or Update User: zendesk.users.createOrUpdate(body)
• Delete User: zendesk.users.delete(id)
• Autocomplete Users: zendesk.users.autocomplete(queryParams)

Groups

• List Group: zendesk.groups.list(queryParams), zendesk.groups.listByUser(userId, queryParams)
• Show Group: zendesk.groups.get(id, queryParams)
• Create Group: zendesk.groups.create(body)
• Update Group: zendesk.groups.update(id, body)
• Delete Group: zendesk.groups.delete(id)

Group Memberships

• List Memberships: zendesk.groupMemberships.list(queryParams), zendesk.groupMemberships.listByUser(userId, queryParams), zendesk.groupMemberships.listByGroup(groupId, queryParams)
• List Assignable Memberships zendesk.groupMemberships.listAssignables(queryParams), zendesk.groupMemberships.listAssignablesByGroup(groupId, queryParams)
• Show Membership: zendesk.groupMemberships.get(id, queryParams), zendesk.groupMemberships.getByUser(userId, id, queryParams)
• Create Membership: zendesk.groupMemberships.create(body)
• Delete Membership: zendesk.groupMemberships.delete(id), zendesk.groupMemberships.deleteByUser(userId, id)
• Set Membership as Default: zendesk.groupMemberships.setAsDefault(userId, membershipId, body)

Tags

  ENTITY_TYPES = {
    organization: 'organizations',
    ticket: 'tickets',
    user: 'users',
  };

• List All Tags: zendesk.tags.list(queryParams)
• List Tags For: zendesk.tags.listFor(ticketId, entity, queryParams)
• Add Tags For: zendesk.tags.addForTicket(ticketId, entity, body)
• Set Tags For: zendesk.tags.setFor(ticketId, entity, body)
• Delete Tags For: zendesk.tags.deleteForTicket(ticketId, entity)