Botmatic integration sdk.


000.4.54 years ago4 years agoMinified + gzip package size for @botmatic/js-integration in KB


Create your Botmatic integration

Botmatic.ai is a keyboard first experience where you design your chatbot by writing a conversation. You can create your own integrations and listen to Botmatic events and actions.


npm install --save @botmatic/js-integration


Require Botmatic

const botmatic = require('@botmatic/js-integration')(settings)

settings is an optional JSON object with the following fields:

Field name Type Description
port Integer optional - Server Express port (3000 by default)
path String optional - Endpoint path where Botmatic will send data with a POST request ("/" by default)
server Express server optional - Your existing Express server
auth Function optionnal - Function to authenticate Botmatic integration client. Take a parameter token (given in header), must return a promise

This library has an Express server embedded. It's optional and you can use your own if you want.

Example with your existing Express server (works with Express 4)

var express = require('express');
var app = express();

const botmatic = require('@botmatic/js-integration')({
  server: app

Example using the Express server included with @botmatic/js-integration

const botmatic = require('@botmatic/js-integration')()

Example using custom authentication

const botmatic = require('@botmatic/js-integration')({
  auth: (token) => {
    return new Promise((resolve, reject) => {
      // Retrieve the client in your database, or other.
      const client_authenticated = {id: "client_id"}
      // If the client is known
      // if not
      // reject();

Listening to actions

In the Botmatic chatbot builder, you can call custom actions during the conversation.

Useful to fetch data from an external source.


  • action name: Regexp you can pass exact action name, or a regexp (e.g: ".*")
  • callback: Function that takes 2 arguments. Should return a Promise.
    • client: Botmatic integration token or your custom client (JSON object) returned by your custom auth function.
    • data: JSON received from Botmatic.
// Tips: you can use regexp for action name.
botmatic.onAction("actionName", ({client, data}) {
  return new Promise((resolve, reject) => {
    resolve({data: {key: "value"}, type: "data"});

Listening to events


  • event name: Regexp you can pass exact event name, or a regexp (e.g: ".*")
  • callback: Function that takes 2 arguments. Should return a Promise.
    • client: Botmatic integration token or your custom client (JSON object) returned by your custom auth function.
    • data: JSON received from Botmatic.
botmatic.onEvent(botmatic.events.CONTACT_UPDATED, function({client, data}) {
  return new Promise((resolve, reject) => {
    resolve({data: "ok", type: "data"});

Events list:

Event name Description
CONTACT_CREATED A contact is created on Botmatic
CONTACT_UPDATED A contact is updated on Botmatic
CONTACT_DELETED A contact is deleted on Botmatic
USER_REPLY A user has just spoke on Botmatic
BOT_REPLY A bot has just replied to a user on Botmatic

Settings page

You can define a settings page, that will be displayed on Botmatic integration form. It used to save your own specific fields to a specific integration token. Usefull when your integration is used by many clients, to differentiate calls by integration token.

Define your settings route

Please define the route to access to your form. You have the token in parameter, to retrieve some data for modification.

The example uses Mustache for templating. It helps to put data in the HTML template.

botmatic.onSettingsPage("/settingspath", async (token) => {
  // Move in global to do it once.
  // Just here for testing
  const Mustache = require('mustache')
  const fs = require('fs')
  const resBuf = fs.readFileSync(__dirname + '/views/fields.html');
  const resStr = resBuf.toString('utf8')

  var tpl = Mustache.render(resStr, {name: "My name", value: "My value"});
  return Promise.resolve(tpl)

Define your form views/fields.html

Please return this HTML structure to be friendly with Botmatic design.

<div class="field is-horizontal">
    <div class="field-label is-normal">
        <label class="label">My iframe field</label>
    <div class="field-body">
        <div class="field">
            <div class="control">
                <input name="{{name}}" placeholder="my placeholder" class="input" value="{{value}}">
            <p class="help">My help.</p>

Define your success form validation

After create the route and template, you can catch the form validation to save data where you want. Botmatic form submit will interrupted if you return success to false, because of some many required missing fields.

botmatic.onUpdateSettings('/settingspath', function(token, data) {
  // Validate data
  // Store them
  // Resolve sucess to true or false
  return Promise.resolve({success: true})

Define your form validation with error

If you have an error, you can resolve with success to false, and errorFields that contains name of input, withj the error to display.

botmatic.onUpdateSettings('/settingspath', function(token, data) {
    success: false,
    errorFields: {
      api_key: "Field required"

Add file inputs

To parse file input, you have to add the parser multer, as:

let multer = require('multer');
let upload = multer();

After that, you will be able to parse the files:

botmatic.onUpdateSettings('/settingspath', function(token, data) {


Enable debug traces by starting your application with:

DEBUG=botmatic* node index.js

More information about Botmatic.ai integrations here

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.