csml-engine

CSML Conversational Engine for nodejs

This package allows you to create CSML chatbots and use them in your own nodejs projects.

CSML is a programming language dedicated to create rich conversational experiences on any chat interface. It helps with defining conversational logic, handling user context, long-term and short-term memory, and integrating with third-party APIs.

For more information about CSML, visit https://csml.dev.

Requirements

In order to use CSML in your program, you will need a MongoDB database. The credentials are loaded from your environment. Please use the .env.example file in this repository as a reference.

Other environment variables are also available:

• DISABLE_SSL_VERIFY=true|false: by default, CSML does not allow invalid (or self-signed) SSL certificates. By setting this to false, you can accept unsafe SSL certificates. Defaults to true.
• ENCRYPTION_SECRET=my_&ncrypti0nS3cr3t!: any string to use as your own encryption key for storing sensitive data safely. If left empty, data will not be encrypted upon storing in the database. Defaults to none.
• DEBUG=true|false: print debug information in console. Defaults to false.

Installation

This projects runs on macOS and linux (ubuntu, debian) out of the box, with nodejs 12.x (lts) and 14.x (latest):

npm install csml-engine

Then, in your project:

import csml from 'csml-engine';

// or
const csml = require('csml-engine');

Compiling from source

For use on other architectures, you will need to compile the project from source into a native node file compatible with your system:

• rust 1.44
• nodejs >= 8.x
• neon-cli 0.4.0 (npm i -g neon-cli@0.4.0)

Then, run the following command:

git clone https://github.com/CSML-by-Clevy/node-csml-engine.git
git submodule update --init --recursive
cd node-csml-engine
npm i

Under native/ you will find a index.node native node file that you can then easily import in your project like any other module:

import csml from './path/to/index.node';

// or
const csml = require('./path/to/index.node');

Usage

Read the documentation to find more informations about the various data formats used in this documentation.

Analyze an incoming event

csml.run(Bot, Event);

Returns:

{
  "request_id": "ec4f47ec-7c99-4b9c-99df-782956aa2cbc",
  "interaction_id": "0b87e25a-f6f4-4617-a10c-a3c725dca3d3",
  "client": {
    "bot_id": "0d1e4c9a-f51b-41bf-8996-e03d8cd44c87",
    "channel_id": "4b229bae-dd10-43b2-877f-7603dc02758d",
    "user_id": "some-user-id"
  },
  "conversation_end": true,
  "messages": [
    {
      "conversation_id": "545f788b-e44d-45ac-a585-93245064ba8d",
      "direction": "SEND",
      "interaction_order": 0,
      "payload": {
        "content": {
          "text": "Hello"
        },
        "content_type": "text"
      }
    }
  ],
  "received_at": "2020-06-09T06:41:37.740Z",
  "is_authorized": true
}

Validate whether a bot contains valid CSML

csml.validateBot(Bot);

Returns:

{
  "valid": false,
  "errors": [
    {
      "message": "Some error message",
      "flow": "name of flow",
      "step": "name of step",
      "line": 123,
      "column": 32
    }
    ...
  ],
  "warnings": [
    {
      "message": "Some warning message",
      "flow": "name of flow",
      "step": "name of step",
      "line": 123,
      "column": 32
    }
    ...
  ]
}

List all the steps in a given flow

csml.getFlowSteps(flow_content);

Find out whether a given client has an open conversation

csml.getOpenConversation(Client);

Returns:

{
  "has_open": true,
  "conversation": Conversation
}

Close any open conversation for a given client

csml.closeAllConversations(Client);