Skip to content

arjunkomath/node-freshdesk-api

Folders and files

NameName
Last commit message
Last commit date
Jun 2, 2022
Jul 3, 2022
Jun 1, 2022
Nov 7, 2022
Jul 3, 2022
Nov 8, 2022
Dec 23, 2016
Dec 23, 2016
Jun 4, 2022
Aug 30, 2017
Jun 1, 2022
Nov 5, 2021
Jun 1, 2020
Sep 26, 2021
Sep 26, 2021
Sep 26, 2021
Sep 26, 2021
May 3, 2016
May 14, 2023
Sep 26, 2021
Sep 26, 2021
Jul 20, 2023
Nov 8, 2022
Nov 3, 2021

Repository files navigation

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!