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.


    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.

    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.

    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 {
        // ...


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

    The Universal Permissive License (UPL), Version 1.0