Node wrapper for Freshdesk v2 API



Thanks 💙


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_:

`shell
npm install freshdesk-api@APIv1
`

Usage

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

Or, with promises:

`javascript
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

$3

`javascript
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);
}
);
`

$3

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

$3

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

$3

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

$3

`javascript
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);
}
);
`

$3

_\* for promisified version only_

`javascript
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:

`js
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

$3

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
`bash
$ DEBUG=freshdesk-api nodejs NAME-OF-YOUR-SCRIPT.js
``

Functions and Responses

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

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

$3

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

$3

- 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

$3

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

$3

- 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

$3

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

$3

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

$3

- 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

$3

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

$3

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

$3

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

$3

SLA = service level agreement

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

$3

- getSettings(callback) - View Helpdesk Settings read more

License

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

[email:arjunkomath]: mailto:arjunkomath@gmail.com
[@maxkoryukov]: https://www.npmjs.com/~maxkoryukov
[@kumarharsh]: https://github.com/kumarharsh
[@davinthesmith]: https://github.com/davinthesmith
[@velua]: http://jjs.life
[@roniger]: https://github.com/roniger

Contributors ✨

Thanks goes to these wonderful people (emoji key):

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

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