Originally published in the Oracle digital assistant blog
In a typical AI-powered chatbot interaction, the user is usually the one who initiates the chat. There are, however, many instances where we need our conversational agent to be able to send out messages that are triggered by an external event.
To support this, ODA 22.08 brought a new enhanced capability called Events* that follows the cloud events specification, which defines common formats for event data to make it interoperable across services, platforms, and systems (https://cloudevents.io/)
*Events require the Visual Flow Designer. Up until now, we had Application Initiated Conversations which is only supported with dialog 1.0 (YAML).
Use Case: Notification for a package delivery
Chatbots can be used for many things, such as ordering food, booking flights, checking the order status, and more. In most of these use cases, there is a back office task that may require some time to be completed, for example, alerting customers when their package is delivered and ready to be picked up.
Let’s imagine a chatbot that alerts a user whenever his package is delivered.
Below are the required steps to enable this notification framework!
Register an Event
The first thing we need is to register the event.
Select Development > Events, click New Event, and enter a name for the event type. This one is called post.status
The field is pre-populated with an example schema that contains the required elements. In the properties object, you define properties as key-value pairs. The event registered here has 3 properties (orderid,status and address).
Configure a Skill to Consume an Event
Next, we need to consume the event. In the skill, create a new flow – this one is called notify.user (do not map to any intent)
Add a state from the template Notify User
The Notify User component has two fields, but we only need to populate the Notification Message which will relay the message back to the user. Below is a message that makes use of expressions to pick up the event property values.
Your order with number ${skill.system.event.value.application.data.orderid} has the status ${skill.system.event.value.application.data.status} and can be picked up from our pick-up point at ${skill.system.event.value.application.data.address}At this moment we do have a flow and a notify user state, but we still need to associate the flow with an application event.
Add Skill to a Digital Assistant
For a skill to consume an external event, it must be part of a digital assistant.
Create a Channel for the External App
Most of the configurations are done, but we still need to create an event channel to route the external event to the proper DA.
Both the Secret Key and the Inbound URL will be necessary in order to enable the external application to communicate with ODA.
Generate an Event from an External App
Now the final piece of the puzzle.
To send events to a digital assistant from an external application, the application must create a POST request to the inbound URL for the event channel where:
- There is an
X-Hub-Signatureheader containing an SHA-256 hash of the request body using the application channel’s secret key. - The content type is
application/cloudevents+json.
This can be done with cURL, REST API, or with any SDK you prefer.
In this particular case, since there is no real application, we can simulate it, by using a sample node.js code (provided in the documentation)
async pushEvent(eventName, eventVersion, userId, channelName, eventData){
try {
const event = {
specversion: "1.0",
id: "6aefc615-26e4-49c3-a761-9a59467dbc2d",
type: eventName,
source: "post.status",
time: "2022-09-07T21:19:24Z",
channelname: channelName,
version: eventVersion,
userid: userId,
data: eventData
};The important values are the ones parameterized. channelName is the name of the event channel (Twilio in our case). eventVersion, the version of the created event and eventName the respective name. The userid value will depend on the channel. In this case, we will use Twilio to enable WhatsApp integration, which means the userId is whatsapp:<phonenumber>. Refer to the documentation to understand the different values that userid may take.
The eventData is a JSON, where data conforms to the event schema previously created.
{
"eventName":"post.status",
"eventVersion" :"1.0",
"userId": "whatsapp:+3161150000",
"channelName":"Twilio",
"eventData":{
"contenttype": "application/json",
"channelName":"Twilio",
"userid":"whatsapp:+3161150000",
"data": {
"orderid": "DT90246",
"status": "DELIVERED",
"address":"Blue street 100, Amsterdam"
}
}
}The documentation provides code to convert the POST body into X-Hub-Signature. Once that is done we can then call the ODA Event REST Endpoint (Inbound URL from the channel event)
Conclusion
By now, everything should be up and running. Typically you may want to have a detailed look at the eventData and the POST body to make sure all parameters are according to the configurations.
Update 22.10
Release 22.10 added new capabilities to the Insights reporting which now includes graphs and metrics that measure the volume, trends, and performance of insights relayed by digital assistants to their skills via the Events channel.
