Skip to content

Latest commit

 

History

History
359 lines (265 loc) · 20.3 KB

README.md

File metadata and controls

359 lines (265 loc) · 20.3 KB
Raw

Node wrapper for Freshdesk v2 API

All Contributors

Build Status codecov

Install

npm install --save freshdesk-api

Also, you could use version 1 of API, provided by Kumar Harsh @kumarharsh, but this version is obsolete, and marked as deprecated:

npm install freshdesk-api@APIv1

Usage

var Freshdesk = require("freshdesk-api");
var freshdesk = new Freshdesk("https://yourdomain.freshdesk.com", "yourApiKey");

Or, with promises:

var Freshdesk = require("freshdesk-api");
var Promise = require("bluebird");
var asyncFreshdesk = Promise.promisifyAll(
	new Freshdesk("https://yourdomain.freshdesk.com", "yourApiKey")
);

// see usage examples

bluebird is not a dependency of this package, install it separately: npm install bluebird

Examples

Create a new ticket

freshdesk.createTicket(
	{
		name: "test ticket",
		email: "test@test.com",
		subject: "test sub",
		description: "test description",
		status: 2,
		priority: 1,
	},
	function (err, data) {
		console.log(err || data);
	}
);

Update a ticket

freshdesk.updateTicket(
	21,
	{
		description: "updated description",
		status: 2,
		priority: 1,
	},
	function (err, data, extra) {
		console.log(err || data);
	}
);

Get a ticket

freshdesk.getTicket(21, function (err, data, extra) {
	console.log(err || data);
});

Delete a ticket

freshdesk.deleteTicket(21, function (err, data, extra) {
	console.log(err || data);
});

Ticket attachments

freshdesk.createTicket(
	{
		description: "test description",
		attachments: [
			fs.createReadStream("/path/to/file1.ext"),
			fs.createReadStream("/path/to/file2.ext"),
		],
	},
	function (err, data) {
		console.log(err || data);
	}
);

Get a ticket PROMISIfied

* for promisified version only

asyncFreshdesk.getTicketAsync(21)
    .then((data, extra) => {
        console.log(data, extra)
    })

    .catch(Freshdesk.FreshdeskError, err => {
        // typed `catch` exists only in bluebird

        console.log('ERROR OCCURED', err)
    })
})

Testing & mocking

Note that node-freshdesk-api is using Undici as an HTTP client, which is not based on Node.js net module. As a result, it is not compatible with popular nock mocking library. When mocking node-freshdesk-api interactions, make sure to use built-in Undici mocking functionality.

Alternatively, you can use tests of node-freshdesk-api itself as an example.

The only exception are forms with attachments (field attachments is set and is an array) - these requests are handled using form-data library, use net module and need to be mocked with nock.

You can also use a mock server (such as Pactum) for completely client-agnostic server mocking.

Use with Webpack

Here is a part of webpack.config:

webpackConfig.node = {
	// ...

	console: true,
	fs: "empty",
	net: "empty",
	tls: "empty",

	// ...
};

A little bit more about webpack here

Callback

Every SDK method receives a callback parameter. It is a function, which will be called on Freshdesk response received.

Callback called with following arguments:

  • err - Error instance (if occured) or null
  • data - object. Freshdesk response, an object, parsed from JSON
  • extra - additional data, gathered from response. For example, information about paging

extra parameter

extra is an object with following fields:

  • pageIsLast - indicates, that the response is generated from the last page, and there is no sense to play with page and per_page parameters. This parameter is useful for listXXX methods, called with pagination
  • requestId - value of x-request-id header from API response

Extended/debugging output

To enable debug info, run your program with environment flags

  • on linux 
    $ DEBUG=freshdesk-api nodejs NAME-OF-YOUR-SCRIPT.js

Functions and Responses

Tickets

  • createTicket(ticket, callback) - Create a new ticket, list of parameters
  • getTicket(id, callback) - Get a ticket by its id
  • updateTicket(id, ticket, callback) - Update a ticket by its id, list of parameters
  • deleteTicket(id, callback) - Delete a ticket by its id
  • restoreTicket(id, callback) - Restore a ticket by its id
  • listAllTickets(filter, callback) - List All Tickets, check list of filters
  • filterTickets(query, page, callback) - Filter tickets, based on ticket fields, read more
  • listAllTicketFields(callback) - List All Ticket Fields
  • listAllConversations(id, callback) - List All Conversations of a Ticket by its id
  • listAllTicketTimeEntries(id, callback) - List All Time Entries of a Ticket by its id
  • listAllSatisfactionRatings - NOT IMPLEMENTED http://developers.freshdesk.com/api/#view_ticket_satisfaction_ratings

Conversations

  • createReply(id, reply, callback) - Create a Reply for a ticket by its id, list of parameters
  • createNote(id, note, callback) - Create a Note for a ticket by its id, list of parameters
  • updateConversation(id, conversation, callback) - Update a conversation by its id, list of parameters
  • deleteConversation(id, callback) - Delete a conversation by its id

Contacts

  • createContact(contact, callback) - Create a new contact, list of parameters
  • getContact(id, callback) - Get a contact by its id
  • updateContact(id, contact, callback) - Update a contact by its id, list of parameters
  • deleteContact(id, callback) - Delete a contact by its id
  • listAllContacts(filter, callback) - List All Contact, check list of filters
  • listAllContactFields(callback) - List All Contact Fields
  • makeAgent(id, callback) - Make a contact an Agent, read more
  • filterContacts(query, callback) - Filter contacts (beta), based on contact fields, read more

Agents

  • getAgent(id, callback) - Get agent by ID read more
  • listAllAgents(params, callback) - List all agents read more
  • updateAgent(id, data, callback) - Update an agent by ID read more
  • deleteAgent(id, callback) - Delete an agent by ID read more
  • currentAgent(callback) - Currently Authenticated Agentread more

Roles

  • getRole(id, callback) - View a Role
  • listAllRoles(callback) - List All Roles

Groups

Not implemented: http://developers.freshdesk.com/api/#groups

Companies

  • createCompany(data, callback) - Create a new company record using parameters
  • getCompany(id, callback) - Get company by ID; read more
  • searchCompany(params, callback) - Get company by name; read more
  • listAllCompanies(params, callback) - List all companies; parameters
  • updateCompany(id, data, callback) - Update a company by ID; parameters
  • deleteCompany(id, callback) - Delete a company by ID, read more
  • filterCompanies(query, callback) - Filter companies (beta), based on company fields, read more
  • listAllCompanyFields(callback) - List All Company Fields

Discussions

Not implemented: http://developers.freshdesk.com/api/#discussions

Solutions

  • createSolutionCategory(data, cb) - Create a Solution Category parameters
  • createTranslatedSolutionCategory(id, language_code, data, cb) - Create a translated solution category parameters
  • updateSolutionCategory(id, data, cb) - Update a Solution Category parameters
  • updateTranslatedSolutionCategory(id, language_code, data, cb) - Update a translated solution category parameters
  • getSolutionCategory(id, cb) - View a Solution Category parameters
  • listAllSolutionCategories(cb) - List all Solution Categories parameters
  • deleteSolutionCategory(id, cb) - Delete a Solution Category parameters
  • createSolutionFolder(id, data, cb) - Create a Solution Folder parameters
  • createTranslatedSolutionFolder(id, language_code, data, cb) - Create a translated solution folder parameters
  • updateSolutionFolder(id, data, cb) - Update a Solution Folder parameters
  • updateTranslatedSolutionFolder(id, language_code, data, cb) - Update a translated solution folder parameters
  • getSolutionFolder(id, cb) - View a Solution Folder parameters
  • listAllSolutionCategoryFolders(id, cb) - List all Solution Folders in a Category parameters
  • deleteSolutionFolder(id, cb) - Delete a Solution Folder parameters
  • createSolutionArticle(id, data, cb) - Create a Solution Article parameters
  • createTranslatedSolutionArticle(id, language_code, data, cb) - Create a translated solution article parameters
  • updateSolutionArticle(id, data, cb) - Update a Solution Article parameters
  • updateTranslatedSolutionArticle(id, language_code, data, cb) - Update a translated solution article parameters
  • getSolutionArticle(id, cb) - View a Solution Article parameters
  • listAllSolutionFolderArticles(id, cb) - List all Solution Articles in a Folder parameters
  • deleteSolutionArticle(id, cb) - Delete a Solution Article parameters
  • searchSolutionArticles(term, cb) - Search solution articles parameters

Surveys

Not implemented: http://developers.freshdesk.com/api/#surveys

Satisfaction Ratings

Not implemented: http://developers.freshdesk.com/api/#satisfaction-ratings

Time Entries

  • createTimeEntry(ticketID, data, callback) - Create new ticket read more
  • listAllTimeEntries(params, callback) - Lists all time entries, if no params pass 'null' read more
  • updateTimeEntry(entryID, data, callback) - Update a time entry by ID read more
  • toggleTimer(entryID, callback) - Toggle timer on time entry by ID read more
  • deleteTimeEntry(id, callback) - Deletes a time entry by ID read more

Email Configs

Not implemented: http://developers.freshdesk.com/api/#email-configs

Products

Not implemented: http://developers.freshdesk.com/api/#products

Business Hours

Not implemented: http://developers.freshdesk.com/api/#business-hours

SLA Policies

SLA = service level agreement

Not implemented: http://developers.freshdesk.com/api/#sla-policies

Settings

  • getSettings(callback) - View Helpdesk Settings read more

License

See the LICENSE file for license rights and limitations (MIT).

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Arjun Komath
Arjun Komath
💻 📖 ⚠️		 Maksim Koryukov
Maksim Koryukov
💻 📖 ⚠️		 DMehaffy
DMehaffy
💻 📖 ⚠️		 John Williamson
John Williamson
💻 📖		 Wouter van der Neut
Wouter van der Neut
💻 📖 ⚠️		 Julián Duque
Julián Duque
💻		 Michael Lambert
Michael Lambert
💻 📖 ⚠️
Pongstr
Pongstr
💻		 Igor Savin
Igor Savin
💻		 jae kaplan
jae kaplan
💻		 Kumar Harsh
Kumar Harsh
💻		 roniger
roniger
💻 📖 ⚠️		 Mohamed Ahmed
Mohamed Ahmed
💻

This project follows the all-contributors specification. Contributions of any kind welcome!