NodeJS SDK

Full NodeJS API reference is hosted on Github

Introduction

With this guide you will learn how to use the Tiledesk JavaScript SDK in your Node.js application. Tiledesk Javascript SDK is built on top of Tiledesk REST APIs.

Before you add Tiledesk SDK to your Node.js app, you need a Tiledesk account and a Tiledesk project. Once you create your project you will have a projectID, a user to play with the project's APIs, a project secret for custom authentication and all the stuff needed to work with Tiledesk and his APIs.

Add Tiledesk to your project

Install TiledeskClient library with npm:

Install

npm install @tiledesk/tiledesk-client

Alternatively use package.json to import the library in the "dependencies" property, as in the following example:

package.json

{
  "name": "Hello Tiledesk nodeJS",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@tiledesk/tiledesk-client": "^0.8.28"
  }
}

Then run:

Install dependencies

npm install

Once installed you can import TiledeskClient() class in your Node.js file using the "require" command:

Import

const { TiledeskClient } = require('@tiledesk/tiledesk-client');

All interaction with Tiledesk APIs uses the TiledeskClient class.

Create a TiledeskClient instance

Before you can use most of the APIs you need to create a TiledeskClient instance. To create the client instance you need a Tiledesk API Key, the project id and an authentication token:

Create instance

const tdclient = new TiledeskClient({
    APIKEY: APIKEY,
    projectId: PROJECT_ID,
    token: USER_TOKEN
})

Additional initialization options:

• {string} options.APIKEY Mandatory. Tiledesk APIKEY

• {string} options.projectId Mandatory. Tiledesk projectId. Will be used in each call on project's APIs.

• {string} options.token Mandatory. Tiledesk authentication token. Will be used in each call on project's APIs.

• {string} options.APIURL Optional. Tiledesk server API endpoint.

• {boolean} options.log Optional. If true HTTP requests are logged.

The most important option is APIURL that provides the opportunity to use TiledeskClient with your own installation of the Tiledesk server.

You can get the token using some authentication method. The token is also provided automatically while you interact with the chatbot using APIs.

Authentication

Before you can interact with Tiledesk APIs you need to authenticate. Tiledesk provides three static authentication methods. Use the stepper below for each.

1

Authentication with email and password

This is the authentication method that you need when working with Tiledesk APIs. Every API method, except authentication ones, work on a project + role + token basis. To authenticate and get a token with email and password use the authEmailPassword() method from the TiledeskClient class. You must provide the APIKEY to authenticate. Actually APIKEYs are experimental and can be omitted. Just use the string 'APIKEY' in place of the real one.

authEmailPassword

TiledeskClient.authEmailPassword(
  'APIKEY',
  /* EMAIL */,
  /* PASSWORD */,
  null,
  function(err, result) {
      if (!err && result) {
          console.log('You got your auth token!', result.token);
          console.log('Your user ID!', result.user._id);
      }
      else {
          console.err("An error occurred", err);
      }
  }
);

In response you will get a token to interact with APIs using your account and the corresponding user ID.

2

Authentication as Anonymous user

This authentication method is useful for anonymous users that need to interact with support APIs.

anonymousAuthentication

TiledeskClient.anonymousAuthentication(
  PROJECT_ID,
  APIKEY,
  null,
  function(err, result) {
    assert(result.token != null);
    let token = result.token;
  }
);

In response you will get a token to interact with APIs in anonymous mode.

3

Custom authentication

With custom authentication you can work with your own users making them auto-signin in Tiledesk without previous signup. This can be used in the place of anonymous authentication to certify users coming from external application, giving them a certified identity in Tiledesk.

For this example import uuid:

Install uuid

npm install uuid

Example:

Custom auth example

const { v4: uuidv4 } = require('uuid');
var externalUserId = uuidv4();
var externalUser = {
    _id: externalUserId,
    firstname:"John",
    lastname:"Wick",
    email: "[email protected]"
};
var signOptions = {
  subject:  'userexternal',
  audience:  'https://tiledesk.com/projects/' + YOUR_PROJECT_ID
};
var jwtCustomToken = "JWT " + jwt.sign(externalUser, YUOR_PROJECT_SECRET, signOptions);

TiledeskClient.customAuthentication(
  jwtCustomToken,
  APIKEY,
  null,
  function(err, result) {
      if (!err && result) {
          let token = result.token;
      }
  }
);

The TiledeskClient class

To interact with Tiledesk APIs you need to create an instance of a TiledeskClient class using its constructor. You MUST supply an APIKEY, an existing Project ID and a valid token (obtained through one of the authentication methods above).

Example: authenticate and create a client instance using the returned token:

Authenticate then create client

TiledeskClient.authEmailPassword(
  'APIKEY',
  /* EMAIL */,
  /* PASSWORD */,
  null,
  function(err, result) {
      if (!err && result) {
          console.log('You got the token!', result.token);
          const tdclient = new TiledeskClient({
              APIKEY: /* APIKEY */,
              projectId: /* PROJECT_ID */,
              token: result.token
          });
      }
      else {
          console.err("An error occurred", err);
      }
  }
);

Working with support requests

A Support Request is a set of metadata and messages decorating a conversation. A Support Request contains data regarding the status (open/assigned/closed etc.), the web/app source page of the conversation, the end-user-id, his email etc. The main information consists of the messages sent and received by the request. Using messaging APIs is indeed the most common way to interact with the request.

You can interact with the request messages using Messaging APIs. Or you can interact directly with Request's metadata using the Request APIs.

Create a support request (send a message)

To create a support request you simply send a message to a not-existing request-id. A new Request object is automatically created by Tiledesk every time you send a message to a non-existing request-id.

You can create a new, UNIQUE request-id using TiledeskClient.newRequestId(PROJECT_ID). Sending a message to this newly created Request ID will automatically create a new Request object, as in the following example:

Create request by sending message

const text_value = 'test message';
const request_id = TiledeskClient.newRequestId(PROJECT_ID);
tdclient.sendSupportMessage(
  request_id,
  {text: text_value},
  (err, result) => {
    assert(err === null);
    assert(result != null);
    assert(result.text === text_value);
});

As soon as you send a new message to Tiledesk with the new request-id, the request is created and ready.

Send messages to a Support Request

With the same sendSupportMessage() function you can send additional messages to the request's conversation. Example sending a second message to the same request:

Send additional message

tdclient.sendSupportMessage(
  request_id,
  {text: 'second message'},
  (err, result) => {
    assert(err === null);
    assert(result != null);
    assert(result.text === text_value);
});

With Tiledesk you can also get sent messages to a request's conversation using Webhooks, subscribing to the Message.create event.

Get a support request by id

Get request by ID

let REQUEST_ID = /* THE REQUEST ID */;
tdclient.getRequestById(REQUEST_ID, (err, result) => {
    const request = result;
    if (request.request_id != null) {
      console.log("Got request with first text:", request.first_text);
    }
});

Query support requests

Query requests

tdclient.getAllRequests(
  {
      limit: 1,
      status: TiledeskClient.UNASSIGNED_STATUS
  },
  (err, result) => {
    assert(result);
    const requests = result.requests;
    assert(requests);
    assert(result.requests);
    assert(Array.isArray(requests));
    assert(result.requests.length > 0);
  }
);

Working with teammates

A Project's teammate is a user who collaborates with you on a specific project.

While the name on the User Interface and documentation level is always teammate, on the APIs level a teammate is called ProjectUser. As the name suggests, a ProjectUser is a Tiledesk User invited with a specific role on a specific Project.

Update teammate status to available/unavailable

With TiledeskClient.updateProjectUserCurrentlyLoggedIn() you will update the status of the user token in the TiledeskClient constructor.

Update availability

const tdclient = new TiledeskClient({
    APIKEY: /* APIKEY */,
    projectId: /* PROJECT_ID */,
    token: result.token
});
tdclient.updateProjectUserCurrentlyLoggedIn(
    {
        user_available: true
    },
    function(err, result) {
        if (!err && result) {
            assert(result);
            assert(result.user_available === true);
        }
    }
);

Check teammate status

Get project user

const tdclient = new TiledeskClient({
    APIKEY: /* APIKEY */,
    projectId: /* PROJECT_ID */,
    token: result.token
});
tdclient.getProjectUser(
  USER_ID,
  function(err, result) {
      if (!err && result) {
          assert(Array.isArray(result));
          assert(result[0]._id != null);
          assert(result[0].user_available === true);
          let PROJECT_USER_ID = result[0]._id;
      }
      else {
          assert.ok(false);
      }
  }
);

The PROJECT_USER_ID variable is the teammate ID of your user (USER_ID) on the PROJECT_ID you specified in the TiledeskClient constructor.

Switch between Cloud and Self hosted instances

Self hosted option

These APIs automatically work with the Tiledesk cloud instance.

If you are running your own self-hosted instance of Tiledesk, the APIs provide a specific option to select your endpoint.

Specify the API endpoint in class methods

If you are using a class method, i.e. authentication methods, use the options.APIURL parameter to specify the endpoint, as in the following example:

Class method with APIURL

TiledeskClient.authEmailPassword(
    APIKEY,
    EMAIL,
    PASSWORD,
    {
      APIURL: API_ENDPOINT
    }
});

Specify the API endpoint in instance methods

If instead you are using instance methods working with an instance of TiledeskClient, you must specify the parameter in the constructor config object as APIURL:

Instance with APIURL

const tdclient = new TiledeskClient({
    APIKEY: APIKEY,
    projectId: PROJECT_ID,
    token: YOUR_TOKEN,
    APIURL: API_ENDPOINT
})

Links

• NodeJS API reference

• Tiledesk REST APIs introduction

• Messaging APIs

• Request APIs

• Management API - groups

• Webhooks

Last updated 2 years ago

This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the privacy policy.