Skip to content
Oracle Bots Node.js SDK
Branch: master
Clone or download
mvandervliet Merge branch 'develop' into 'master'
PATCH - minor fixes

See merge request intelligent-bots-cloud-service/bots-js-sdk!12
Latest commit abe4f9e Dec 6, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Bugfix #3 - Spawn ENOENT on windows Dec 6, 2018
config Addresses initial SCS analysis Aug 22, 2018
middleware lint webhook Oct 17, 2018
testing refactor sample and updated docs Oct 22, 2018
ts Fix undefined prototype during registry creation Nov 2, 2018
util MIECS-10401: refactored to use node-fetch in place of axios Sep 20, 2018
.eslintrc Replaced ts with js source Feb 26, 2018
.gitignore Migrated to nyc for child process coverage Oct 30, 2018
.npmignore Fixed ignore template spec Nov 9, 2018
.nvmrc Everything working + tests in place Nov 22, 2017
.nycrc Added contributing details Aug 8, 2018 Restored readme change and starter spec addition Nov 9, 2018 updated docs and 3p Sep 20, 2018
index-browser.js removed browser trailing comma Aug 31, 2018
index.js adjustments on codequality Aug 24, 2018
package-lock.json 2.1.3 Dec 6, 2018
package.json adjustments on codequality Aug 24, 2018
tslint.json updates to reflect 18.2.3 Mar 14, 2018
wercker.yml Added configuration and modifications for wercker integration Aug 20, 2018

Oracle Bots Node.js SDK

This SDK is the main developer resource for Oracle Bots integrations in a Node.js express environment. This package provides two primary solutions for custom implementations against the Oracle Bots platform: Running Custom Component Services and/or Webhook Channels.

  • Installation - Installation and usage information.
  • CLI - Developer tools and utilities for getting started.
  • Custom Component - Services to enrich a conversation flow with custom logic, API integrations, messages, and more.
  • Webhook - Integrate with custom messaging channels using incoming/outgoing webhook.
  • Documentation - Full SDK documentation.

npm version wercker status


npm install @oracle/bots-node-sdk

Most often, this package is installed as a dependency of an express application where any appropriate middleware is then applied.

The SDK also ships CLI tools with some quick start project generators.


This package includes several command line capabilties designed to facilitate custom development with the SDK itself. See complete documentation here

npx @oracle/bots-node-sdk --help

Basic Setup

const express = require('express');
const OracleBot = require('@oracle/bots-node-sdk');

const app = express();
// implement custom bot services... (see below)

Custom Logging

If verbose logging details are desired, you may configure a logging utility of your choice, and initialize the SDK accordingly.

OracleBot.init(app, {
  logger: console,

Custom Components

Each state within a Bot flow calls a component to perform actions ranging from basic interactions like user input and outputting response text to some service-specific actions like fulfilling an order or booking a flight.

The platform has many built-in components to support basic actions like setting variables, allowing OAuth, and enabling user input. In cases where your bot design calls for unique actions outside of these functions, you’ll be writing Custom Components. These allow your bot to call REST APIs, implement business logic, transition state, customize messages, etc.

This package provides the necessary middleware and libraries for incorporating Custom Components into your Bot dialog.

QuickStart for Custom Components

Custom Component Service

The API for exposing custom components to your bot is established using the middleware included in this package.

Initializing the component middleware includes some basic configurations. Most important is the register option, which specifies component paths or component objects - telling the service where Custom Component sources are located within your project.

  • cwd string - Top level directory to which all other paths are relative. (__dirname is recommended).
  • register (string|object(s)|function)[] - Defines component registry from array of the paths to resolve.
    • String paths may also be directories, which are scanned recursively and added to the registry.
    • Multiple components may also be exported from a single file.
const express = require('express');
const OracleBot = require('@oracle/bots-node-sdk');

const app = express();

// implement custom component api
OracleBot.Middleware.customComponent(app, {
  baseUrl: '/components',
  cwd: __dirname,
  register: [

Custom Component Code

Using the @oracle/bots-node-sdk for Custom Component development supports a flexible approach to authoring components. This means that many structures for the implementation of a Custom Component are possible. Whatever the approach, the fundamental interface is required as follows:

// interface for a custom component implementation
  metadata(): {name: string, properties?: {[name:string]: string}, supportedActions?: string[]};
  invoke(conversation: Conversation, done: () => {}): void;

One supported implementation is to use a simple object with metadata and invoke members:

// mycomponent.js
module.exports = {
  metadata: () => ({
    name: 'my.custom.component',
    properties: {},
    supportedActions: []
  invoke: (conversation, done) => {

You may also wish to define a component by exporting class(es) and optionally extending the ComponentAbstract class for additional convenience members. NOTE Component classes are instantiated as singletons.

// mycomponent.js
const { ComponentAbstract } = require('@oracle/bots-node-sdk/lib');

module.exports = class MyComponent extends ComponentAbstract {
  metadata() {
    return {
      name: 'my.custom.component',
      properties: {},
      supportedActions: []
  invoke(conversation, done) {


The fundamental mechanism for sending and receiving messages with the Bot platform is through asynchronous inbound and outbound messaging. The platform supports several built-in channels natively, and webhook for any other messaging service or client.

Implementing webhook as a channel can differ greatly across clients. Generally each client uses a unique message format, and different mechanisms for sending or receiving messages. This package includes these necessary integration tools.

QuickStart for Webhook

Webhook Client

WebhookClient is a flexible library for integrating with webhook channels configured within your bot. Refer to the documentation and examples to further understand ways the webhook client may be implemented.

const express = require('express');
const OracleBot = require('@oracle/bots-node-sdk');

const app = express();

// implement webhook
const { WebhookClient, WebhookEvent } = OracleBot.Middleware;

const channel = {
  url: process.env.BOT_WEBHOOK_URL,
  secret: process.env.BOT_WEBHOOK_SECRET
const webhook = new WebhookClient({ channel: channel });
webhook.on(WebhookEvent.ERROR, console.error); // receive errors

// receive bot messages'/bot/message', webhook.receiver()); // receive bot messages
webhook.on(WebhookEvent.MESSAGE_RECEIVED, message => {
  // format and send to messaging client...

// send messages to bot (example)'/user/message', (req, res) => {
  let message = {/* ... */}; // format according to MessageModel
    .then(() => res.send('ok'), e => res.status(400).end());

TIP send() supports an optional channel as its second argument, thereby handling request-specific channel determination.

Webhook Utilities

While WebhookClient is designed to support the majority of possible integration types, there may be cases where further control is needed. For this reason, and to support the full spectrum of integration designs, a series of utilities are exposed directly for interfacing with the platform's webhook channel.

const { webhookUtil } = require('@oracle/bots-node-sdk/util');
// ...
webhookUtil.messageToBotWithProperties(url, secret, userId, messsage, extras, (err, result) => {


Message Formatting

The Oracle Bots platform supports several message formats, as defined by the MessageModel class.

The class provides several static methods used to create a stuctured object of a known Common Message Model message such as Text, Card, Attachment, Location, Postback or Raw type. It can be used within Custom Components, Webhook, or independently. In addition, MessageModel can be used in browsers. When used in browser, include the package joi-browser.

const { MessageModel } = require('@oracle/bots-node-sdk/lib');
// or
const OracleBot = require('@oracle/bots-node-sdk');
const { MessageModel } = OracleBot.Lib;

TIP: Use conversation.MessageModel() to access from within a Custom Component invoke method. Use webhook.MessageModel() to access from within a WebhookClient instance.

Method Purpose Usage
textConversationMessage Basic text inbound, outbound
attachmentConversationMessage Support media URLs inbound, outbound
cardConversationMessage Card presentation outbound
postbackConversationMessage Submit postback payloads inbound
locationConversationMessage Receive location payload inbound
rawConversationMessage Freeform payload inbound, outbound

MessageModel Utilities

Additionally, a set of utilities for MessageModel are provided. Util.MessageModel functions help deriving string or speech representation of a Conversation Message Model payload. This is used primarily to output text or speech to voice or text-based channels like Alexa and SMS.

const { messageModelUtil } = require('@oracle/bots-node-sdk/util');
// ...

Unit Testing

The SDK also includes unit testing facilities, which can be utilized within your preferred test runner. Details may be found here.

Using TypeScript

This package includes types, and can therefore be used directly with TypeScript.

import { Lib } from '@oracle/bots-node-sdk';

class MyCustomComponent implements Lib.IComponent {
  public metadata(): Lib.IComponentMetadata {
    return { name: 'my.custom.component' }
  public invoke(conversation: Lib.Conversation, done: () => void): void {
    // ...


@oracle/bots-node-sdk is an open source project. See CONTRIBUTING for details.


Copyright © 2018, Oracle and/or its affiliates. All rights reserved.

The Universal Permissive License (UPL), Version 1.0

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.