WebhookClient

Middleware. WebhookClient

Webhook class for custom messaging implementations.

Constructor

new WebhookClient(optionsopt)

Source:
See:
Example

Simple client for sending and receivinng messages.

const OracleBot = require('@oracle/bots-node-sdk');
const express = require('express');
const app = express();
OracleBot.init(app); // init main application layer

// define webhook channel configuration.
// can also be function (req => WebhookChannel | Promise<WebhookChannel>)
const channel = {
  url: process.env.BOT_WEBHOOK_URL,
  secret: process.env.BOT_WEBHOOK_SECRET
};
const webhook = new OracleBot.Middleware.WebhookClient({ channel });

// receive messages from bot and forward to user
app.post('/webhook/receiver', webhook.receiver((req, res) => {
  const { userId, messagePayload } = req.body;
  // Message was received and validated from bot. Forward to user accordingly...
}))

// receive messages from a client webhook and forward to bot
app.post('/webhook/:client/message', (req, res) => {
  let message = {};
  // assign userId, messagePayload, profile, etc... on message and send
  webhook.send(message)
   .then(() => res.send('ok'), e => res.status(400).send())
});
Parameters:
Name Type Attributes Description
options WebhookClientOptions <optional>

Methods

MessageModel() → {MessageModel}

Description:
  • Returns the MessageModel class for creating or validating messages to or from bots.
Source:
Returns:
The MessageModel class
Type
MessageModel

on(event, handler) → {WebhookClient}

Description:
  • Subscribe to WebhookClient events
Source:
Parameters:
Name Type Description
event WebhookEvent Event type to subscribe
handler WebhookEventHandler Event handler
Returns:
Type
WebhookClient

receiver(callbackopt) → {WebhookReceiverMiddleware}

Description:
  • Receiver middleware to handle messages incoming from bot. If used without callback, messages will be dispatched to any subscribers to the WebhookEvent.MESSAGE_RECEIVED event.
Source:
Parameters:
Name Type Attributes Description
callback WebhookReceiverCallback <optional>
 Optional callback for received messages from bot.
Returns:
Type
WebhookReceiverMiddleware

send(message, channelopt)

Description:
  • Send client message to bot
Source:
See:
Parameters:
Name Type Attributes Description
message object Complete payload to send
channel WebhookChannel <optional>
 Webhook channel configuration to use (if different than that in the instance options)

Type Definitions

WebhookChannel

Description:
  • Configuration details for sending messages to bots on a webhook channel.
Source:
Properties:
Name Type Description
url string Webhook url issued by bots platform channel
secret string Message signature secret key used to create X-Hub-Signature
Configuration details for sending messages to bots on a webhook channel.
Type:
  • Object

WebhookChannelCallback(reqopt) → {WebhookChannel|Promise.<WebhookChannel>}

Description:
  • Callback used by webhook client to obtain channel configuration information for a given request.
Source:
Example
const { WebhookClient, WebhookEvent } = require('@oracle/bots-node-sdk').Middleware;

function getChannelForReq(req) {
  const client = req.params.client;
  return {
    url: 'https://...',  // Oracle bot webhook url specific to client
    secret: '...',       // webhook channel secret key
  }
}

const webhook = new WebhookClient({
  channel: getChannelForReq,
});

app.post('/bot/messages', webhook.receiver());
webhook.on(WebhookEvent.MESSAGE_RECEIVED, message => {
  const { userId, messagePayload } = message;
  // format and send to user.
});
Parameters:
Name Type Attributes Description
req external:ExpressRequest <optional>
 The request object originally sent to the endpoint
Returns:
Type
WebhookChannel | Promise.<WebhookChannel>

WebhookClientOptions

Description:
  • Options to configure a webhook client endpoint where messages are forwarded to the bot on a webhook channel.
Source:
Properties:
Name Type Attributes Description
channel WebhookChannel | WebhookChannelCallback <optional>
 Webhook channel configuration or callback.
Options to configure a webhook client endpoint where messages are forwarded to the bot on a webhook channel.

WebhookEvent

Description:
  • WebhookEvent enum for WebhookClient event subscriptions
Source:
WebhookEvent enum for WebhookClient event subscriptions
Example
const { WebhookClient, WebhookEvent } = require('@oracle/bots-node-sdk').Middleware;

const webhook = new WebhookClient({
  channel: // ...
});
//... 
webhook.on(WebhookEvent.ERROR, error => {
  // webhook error
  console.error(error);
});
webhook.on(WebhookEvent.MESSAGE_RECEIVED, message => {
  // message received from bot. 
  // Format and send to user...
});
webhook.on(WebhookEvent.MESSAGE_SENT, message => {
  // message was sent to bot.
});

WebhookEventHandler(detail) → {void}

Description:
  • Callback handler for WebhookClient event emitter.
Source:
Parameters:
Name Type Description
detail * Event detail payload.
Returns:
Type
void

WebhookReceiverMiddleware(req, res, next) → {void}

Description:
  • Callback function upon successful webhook validation. Further validations may be performed, and it is required to send the response for the webhook request. as res.send, res.json, etc. Note that this response is NOT a message back to the bot.
Source:
Parameters:
Name Type Description
req external:ExpressRequest Request with validated req.body
res external:ExpressResponse Response to bots webhook request
next function Express NextFunction
Returns:
Type
void