@botmock/client

@botmock/client

Overview

This package is used to extract data from Botmock projects.

Install

The package is available to install on npm.

npm install @botmock/client

Guide

The following guides assumes a TypeScript environment with LTS Node.js installed.

Note: You can bootstrap such an environment by running npx @botmock/cli

Note: Tokens and ids are created and accessed using the Botmock dashboard

Let's walk through building a small Node.js app that fetches data from multiple Botmock projects.

// index.ts
import { Client } from "@botmock/client";

const client = new Client();

(async () => {
  const projects = await client
    .withToken("YOUR_TOKEN")
    .forTeam("YOUR_TEAM_ID")
    .withProjectIds(["PROJECT_ID_1", "PROJECT_ID_2"])
    .getProjects();

  console.log(projects); // array of project objects
})();

Running ts-node index.ts should print an array of project objects.

API

Client

Chaining methods

Once a new instance of Client is made, the following chaining methods can be chained together to build requests.

• .withToken(string)
• .forTeam(string)
• .onBoard(string)
• .withProjectIds(string[])

To execute requests, the following methods can be used at the end of a build chain. Listed below each of these dispatch methods are the required chaining methods.

• .getProjects()
  • .withToken(string)`
  • .forTeam(string)
  • .withProjectIds(string[])
• .getBoards()
  • .withToken(string)`
  • .forTeam(string)
  • .onBoard(string)
  • .withProjectIds(string[])
• .getTeams()
  • .withToken()
  • .forTeam(string)
  • .withProjectIds(string[])
• .getPaths()
  • .withToken(string)`
  • .forTeam(string)
  • .onBoard(string)
  • .withProjectIds(string[])

getResources

As an alternative to the chaining approach outlined above, resources can be fetched in a single method call.

Returns a Promise which resolves an object containing payloads for each of resources provided in the options object.

The options object contains the following.

Key name	Type	Description
teamId	string	id of the team
projectId	string	id of the project
boardId	string	(optional) id of the board
resources	string[]	array of "project", "team", "board", "intents", "variables", or "entities"

import { Client, Resource } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const { project, team, board, intents, variables, entities } = await client.getResources({
    teamId: "YOUR_TEAM_ID",
    projectId: "YOUR_PROJECT_ID",
    boardId: "YOUR_BOARD_ID",
    resources: [
      Resource.PROJECT,
      Resource.TEAM,
      Resource.BOARD,
      Resource.INTENTS,
      Resource.VARIABLES,
      Resource.ENTITIES,
    ]
  });
  // Each destructured property above contains that slice of data from the Botmock project specified in the options object.
})();

The object returned by getResources can look like the following.

{
  "project": {
    "id": "637882f0-93ab-11ea-8c14-4d6810dd96fc",
    "name": "complex",
    "type": "flow",
    "platform": "multi-channel",
    "channels": [
      "generic"
    ],
    "locales": [
      "en"
    ],
    "created_at": {
      "date": "2020-05-11 17:18:10.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2020-06-26 16:39:01.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  },
  "team": {
    "id": 1831,
    "name": "Botmock Team",
    "photo": "http://az6wlss5f1.cloud.wal-mart.com/storage/profiles/Wp5VXSQ4LUTSkfLKlH7IIOgXmkDcQh5OXhaghtFv.png",
    "created_at": {
      "date": "2017-08-12 03:38:19.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  },
  "board": {
    "board": {
      "root_messages": [
        "637a5d70-93ab-11ea-a217-33512b13de41"
      ],
      "messages": [
        {
          "message_id": "637a5f60-93ab-11ea-a478-8debb9e9d485",
          "message_type": "response",
          "next_message_ids": [
            {
              "message_id": "27074d90-b3df-44b3-8e4e-c9b8802dad61",
              "action": "*",
              "intent": {
                "label": "give_party_size",
                "value": "da7ccf40-b7ca-11ea-8ff6-c37e8170426d"
              },
              "conditional": {
                "id": "g-DsAWYCMF1acBzPXVRVi0z",
                "rules": [],
                "combinator": "and",
                "not": false
              }
            }
          ],
          "previous_message_ids": [
            {
              "message_id": "637a5d70-93ab-11ea-a217-33512b13de41",
              "action": "*"
            }
          ],
          "is_root": false,
          "node_name": "Bot Says",
          "payload": {
            "en": {
              "generic": {
                "blocks": [
                  {
                    "component_type": "text",
                    "nodeName": "Bot Says",
                    "context": [
                      {
                        "id": "a0a11bd0-b7ca-11ea-a1cf-4155954aa7c8",
                        "name": "%name%",
                        "type": "text",
                        "entity": "",
                        "default_value": "",
                        "start_index": 3
                      }
                    ],
                    "text": "Hi %name%, how many for your reservation?",
                    "audio_file": "",
                    "ssml": "",
                    "delay": 2000,
                    "alternate_replies": [
                      "one"
                    ]
                  }
                ]
              }
            }
          }
        }
      ]
    },
    "slots": {},
    "variables": [
      {
        "id": "a0a11bd0-b7ca-11ea-a1cf-4155954aa7c8",
        "name": "name",
        "default_value": "",
        "type": "text",
        "entity": "",
        "created_at": {
          "date": "2020-06-26 16:32:29.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "updated_at": {
          "date": "2020-06-26 16:32:29.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        }
      }
    ],
    "created_at": {
      "date": "2020-05-11 17:18:10.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2020-06-26 16:36:24.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  },
  "intents": [
    {
      "id": "1fbe2430-b7cb-11ea-86a3-61a8fe026c9c",
      "name": "done",
      "utterances": {
        "en": [
          {
            "text": "done",
            "variables": []
          }
        ]
      },
      "created_at": {
        "date": "2020-06-26 16:36:02.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2020-06-26 16:36:11.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "is_global": false,
      "slots": []
    }
  ],
  "variables": [
    {
      "id": "a0a11bd0-b7ca-11ea-a1cf-4155954aa7c8",
      "name": "name",
      "default_value": "",
      "type": "text",
      "entity": "",
      "created_at": {
        "date": "2020-06-26 16:32:29.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2020-06-26 16:32:29.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    }
  ],
  "entities": []
}

getProject

Returns a Promise which resolves an object containing high-level project data.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const project = await client.getProject("YOUR_TEAM_ID", "YOUR_PROJECT_ID");
  // `project` contains the project data specified by the team id and project id passed to the method.
})();

getProjects

Returns a Promise which resolves an array of objects containing high-level project data.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const projects = await client.getProjects([{ teamId: "YOUR_TEAM_ID", projectId: "YOUR_PROJECT_ID" }]);
  // `projects` contains the project data specified by the series of team ids and project ids passed to the method.
})();

getTeam

Returns a Promise which resolves an object containing high-level team data.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const team = await client.getTeam("YOUR_TEAM_ID");
  // `team` contains the team data specified by the team id passed to the method.
})();

getTeams

Returns a Promise which resolves an array of objects containing high-level team data.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const teams = await client.getTeams(["YOUR_TEAM_ID"]);
  // `teams` contains the team data specified by the team ids passed to the method.
})();

getBoard

Returns a Promise which resolves an object describing the specified board.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const board = await client.getBoard("YOUR_TEAM_ID", "YOUR_PROJECT_ID", "YOUR_BOARD_ID");
  // `board` contains the board data specified by the ids passed to the method.
})();

getBoards

Returns a Promise which resolves an array of objects describing the specified boards.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const boards = await client.getBoards("YOUR_TEAM_ID", "YOUR_PROJECT_ID", ["YOUR_BOARD_ID_1"]);
  // `boards` contains the board data specified by the ids passed to the method.
})();

getIntents

Returns a Promise which resolves an array of objects containing intent data for the specified project.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const intents = await client.getIntents("YOUR_TEAM_ID", "YOUR_PROJECT_ID");
  // `intents` contains the intent data specified by the team id and project id passed to the method.
})();

getVariables

Returns a Promise which resolves an array of objects containing variables data for the specified project.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const variables = await client.getVariables("YOUR_TEAM_ID", "YOUR_PROJECT_ID");
  // `variables` contains the variables data specified by the team id and project id passed to the method.
})();

getEntities

Returns a Promise which resolves an array of objects containing entities data for the specified project.

import { Client } from "@botmock/client";

const client = new Client({ token: "YOUR_TOKEN" });

(async () => {
  const entities = await client.getVariables("YOUR_TEAM_ID", "YOUR_PROJECT_ID");
  // `entities` contains the entities data specified by the team id and project id passed to the method.
})();