zendesk-node-api

A wrapper library for Zendesk using NodeJS

Getting started

Install the package via npm

$ npm install zendesk-node-api

Create a new instance of Zendesk passing in your Zendesk URL, email and API token.

var Zendesk = require('zendesk-node-api');

var zendesk = new Zendesk({
  url: YOUR_ZENDESK_URL, // https://example.zendesk.com
  email: YOUR_ZENDESK_EMAIL, // me@example.com
  token: YOUR_ZENDESK_API_TOKEN // hfkUny3vgHCcV3UfuqMFZWDrLKms4z3W2f6ftjPT
});

You can also use a OAuth2 authentication to get the token, then you need to create a new instance of Zendesk like this:

var Zendesk = require('zendesk-node-api');

var zendesk = new Zendesk({
  url: YOUR_ZENDESK_URL, // https://example.zendesk.com
  token: YOUR_ZENDESK_OAUTH_TOKEN // hfkUny3vgHCcV3UfuqMFZWDrLKms4z3W2f6ftjPT,
  oauth: true
});

Please note that when using OAuth token you won't need an e-mail.
According to the Zendesk documentation OAuth2 token will never expire, so no need to refresh it. More information about it you can find here.

Available objects

• ``tickets`
• `ticketFields`
• `users`
• `userFields`
• `macros`
• `search` - Only .list(/ URL params /)` method.

I'll be adding more objects, I'm aiming for 100% test coverage so it may take a little time.

List

Return an array of all items in the object

zendesk.objects.list(
  // (Optional) URL params available for each object.
  // https://developer.zendesk.com/rest_api/docs/core/
).then(function(result){
    console.log(result);
});

Show

Return an item from an ID

zendesk.objects.show(OBJECT_ID).then(function(result){
    console.log(result);
});

Create

Create an item using keys and values from the Zendesk documentation.

zendesk.objects.create({
    // keys and values from the zendesk docs
    // https://developer.zendesk.com/rest_api/docs/core/
}).then(function(result){
  // result == true
})

Update

Update an item from and ID using keys and values from the Zendesk documentation.

zendesk.objects.update(OBJECT_ID, {
    // keys and values from the zendesk docs
    // https://developer.zendesk.com/rest_api/docs/core/
}).then(function(result){
    console.log(result);
})

Delete

Delete an item from ID

zendesk.objects.delete(OBJECT_ID).then(function(result){
    // result == true
});

Example

// List all tickets

zendesk.tickets.list().then(function(tickets){
  console.log(tickets);
});

// List all tickets and sort by status and order descendent
// https://developer.zendesk.com/rest_api/docs/core/tickets#list-tickets

zendesk.tickets.list('sort_by=status&sort_order=desc').then(function(tickets){
  console.log(tickets);
});

// Show a single ticket

zendesk.tickets.show(TICKET_ID).then(function(ticket){
  console.log(ticket);
});

// Create a ticket

zendesk.tickets.create({
  subject: 'A new ticket',
  comment: {
    body: 'A ticket created with zendesk-node-api'
  }
}).then(function(result){
  console.log(result);
});

// Update a ticket

zendesk.tickets.update(TICKET_ID, {
  subject: 'An updated subject'
}).then(function(result){
  console.log(result);
});

// Delete a ticket

zendesk.tickets.delete(TICKET_ID).then(function(result){
  // result == true
});

// List all open tickets

zendesk.search.list('query=type:ticket status:open').then(function(results){
  console.log(results);
});

Develop

1. Rename .env.example to .env and add your Zendesk URL, email and API token.
2. Rename test/models/config.js.example to /test/models/config.js.
3. Run npm test, some of the tests will fail, don't worry about it for now.
4. Update /test/models/config.js using IDs found from CURL. (see example below)
5. Run npm test, if your configuration is set correctly, there should be no failing tests.

Using CURL to get configuration IDs

# Tickets
curl https://{subdomain}.zendesk.com/api/v2/tickets.json -v -u {email_address}:{password}

# Users
curl https://{subdomain}.zendesk.com/api/v2/users.json -v -u {email_address}:{password}

# User fields
curl https://{subdomain}.zendesk.com/api/v2/user_fields.json -v -u {email_address}:{password}

# Macros
curl https://{subdomain}.zendesk.com/api/v2/macros.json -v -u {email_address}:{password}