search

crisp-im / node-crisp-api

:zap: Crisp API Node Wrapper
https://docs.crisp.chat/guides/rest-api/
MIT License
99 stars 38 forks source link
api chat integration livechat messenger rest websocket widget wrapper

readme

Crisp API Wrapper

Test and Build Build and Release Version Downloads

The Crisp API Node wrapper. Authenticate, send messages, fetch conversations, access your agent accounts from your JavaScript code.

Copyright 2024 Crisp IM SAS. See LICENSE for copying information.

Installation

npm install --save crisp-api

Authentication

To authenticate against the API, obtain your authentication token keypair by following the REST API Authentication guide. You'll get a token keypair made of 2 values.

Keep your token keypair values private, and store them safely for long-term use.

Then, add authentication parameters to your client instance right after you create it:

var Crisp = require("crisp-api");
var CrispClient = new Crisp();

// Authenticate to API with your plugin token (identifier, key)
// eg. CrispClient.authenticate("7c3ef21c-1e04-41ce-8c06-5605c346f73e", "cc29e1a5086e428fcc6a697d5837a66d82808e65c5cce006fbf2191ceea80a0a");
CrispClient.authenticateTier("plugin", identifier, key);

// Now, you can use authenticated API sections.

Overview

You may follow the REST API Quickstart guide, which will get you running with the REST API in minutes.

var Crisp = require("crisp-api");
var CrispClient = new Crisp();

CrispClient.authenticateTier("plugin", identifier, key);

CrispClient.website.listConversations(websiteID, 1)
  .then(function(conversations) {
    console.log("Listed conversations:", conversations);
  })
  .catch(function(error) {
    console.error("Error listing conversations:", error);
  });

Examples

Create your own bot!

var Crisp = require("crisp-api");
var CrispClient = new Crisp();

CrispClient.authenticateTier("plugin", identifier, key);

// Notice: make sure to authenticate before listening for an event
CrispClient.on("message:send", function(message) {
  CrispClient.website.sendMessageInConversation(
    message.website_id, message.session_id,

    {
      type    : "text",
      content : "I'm a bot",
      from    : "operator", // or user
      origin  : "chat"
    }
  )
    .then(function(message) {
      console.log("Message sent:", message);
    })
    .catch(function(error) {
      console.error("Error sending message:", error);
    });
})
  .then(function() {
    console.error("Requested to listen to sent messages");
  })
  .catch(function(error) {
    console.error("Failed listening to sent messages:", error);
  });

Resource Methods

All the available Crisp API resources are fully implemented. Programmatic methods names are named after their label name in the REST API Reference.

All methods that you will most likely need when building a Crisp integration are prefixed with a star symbol (⭐).

⚠️ Note that, depending on your authentication token tier, which is either user or plugin, you may not be allowed to use all methods from the library. When in doubt, refer to the library method descriptions below. Most likely, you are using a plugin token.

Website
Plugin
Media
Bucket
RTM Events

Website

👉 Notice: The peopleID argument can be an email or the peopleID.

Plugin

Media

Bucket

Realtime Events

You can bind to realtime events from Crisp, in order to get notified of incoming messages and updates in websites.

You won't receive any event if you don't explicitly subscribe to realtime events, as the library doesn't connect to the realtime backend automatically.

There are two ways to receive realtime events:

  1. Using Web Hooks (⭐ recommended)
  2. Using WebSockets with the RTM API

Before you start with RTM events, please consider the following:

Receive realtime events

Receive events over Web Hooks

To start listening for events and bind a handler, check out the events over Web Hooks example.

You will need to adjust your code so that:

  1. The RTM events mode is set to Web Hooks: CrispClient.setRtmMode(Crisp.RTM_MODES.WebHooks)
  2. Your HTTP endpoint mounts a route listening for POST requests, and upon receiving requests:
    1. It verifies the requests with: CrispClient.verifyHook(secret, body, timestamp, signature)
    2. It receives the Web Hook with: CrispClient.receiveHook(body)

Plugin Web Hooks will need to be configured first for this to work. Check out our Web Hooks Quickstart guide and our Web Hooks Reference to get started.

Receive events over WebSockets (RTM API)

To start listening for events and bind a handler, check out the events over WebSockets example.

You will need to adjust your code so that:

  1. The RTM events mode is set to WebSockets: CrispClient.setRtmMode(Crisp.RTM_MODES.WebSockets)

Available realtime events

Available events are listed below: