The Oracle Digital Assistant supports several channels out of the box. If you need to integrate with Slack, MS Teams, FB Messenger, or connect to iOS or Android. These are all native ODA channels, and that means that the webhook implementation is complete including all the message transformation and the bot developer does not need to create anything else. One only needs to configure the connection to make everything work.
What if your channel or messaging service is not supported out of the box? Then you can use an a webhook channel to manually integrate Oracle Digital Assistant with it.
Step 1 – Download Bots Node SDK
The bots-node-sdk is available on https://github.com/oracle/bots-node-sdk
You can download the project as a zip.
Then you can find the sample start folder under bots-node-sdk-master\examples\webhook\starter
I copied that folder to my IDE and that is my starting point.
index.js is the node express server and we can start it with npm start
service.js is where we will implement the core logic, and where the bot listeners and senders are placed.
package.json contains all the required modules
Step 2 – Install project dependencies
If you are familiar with node.js then this is an obvious step.
The below line will install everything specified in package.json -> @oracle/bots-node-sdk and express.
npm install
Step 3 – Implement the webhook
All of the work happens in the service.js file. This is where the logic is contained. Let’s look at the sample code.
There are two main blocks, one to handle the webhook events – webhook.on(EVENT_TYPE), and another to receive the messages from the client (app.post(‘/test/message’)
line 31: Webhook receiver that is triggered when ODA sends a message back. This will in turn trigger the event handler from line 19
line 43: Webhook sender, that sends a message to ODA .
The above is the untouched sample file.
We need to do some minor changes for this to work. The required request data are a unique userId and messagePayload, so we need to get that information from the client. Since this will be a mockup client request sent via POSTMAN, I just define user and text accordingly.
Step 4 – Create an ODA Channel
For developing purposes we can use ngrok which will provide a tunnel between my local machine and ODA.
Then when we create a Webhook Channel in ODA where we want to expose our Skill, we place the ngrok URI into the Outgoing Webhook URI fields.
IMPORTANT: The ngrok url is appended with /bot/message which is defined in service.js as the receiver method, listening for events -> app.post(‘/bot/message’, webhook.receiver());
Step 5 – Update the Webhook URL and Secrete
Then we use the Channel URI and Secrete to update the placeholder in service.js
Step 6 – Test the Webhook server
Everything should be set now, we just need to start the server and emulate a client.
node index.jsand you should see inline
oracle-bot-webhook service onlineFrom POSTMAN we can emulate a client request.
and on the IDE terminal we get
Below is the code that the event MESSAGE_RECEIVED triggers -> execution of the logger.info to the console.
In a real implementation this would call the messaging platform API/SDK.
and I could send more rest requests
not a very easy way of having a conversation, but it goes to show that the webhook works, and that from this point onwards we would only need to “plug-in” the messenger API provider.
In the next Post I will expand this webhook to act as a channel for Twitter.