Executive Summary
Oracle Digital Assistant (ODA) is usually seen as a conversation tool where users initiate the dialog. However, ODA can also be used to provide notifications to a user based on any event of interest. ODA can listen to events from external applications and send notifications accordingly to the targeted users. The messages would pop up when the user is in the ODA widget. This feature in ODA to consume external CloudEvents is supported in Visual Flow Designer (VFD) only. As ODA supports user conversations over different channels like MS-Teams, Slack, Twilio and others, the notifications can be sent seamlessly across different channels with channel-specific payloads. External applications need to be configured to send a REST payload to the ODA event channel to initiate the notification flow. This blog attempts to describe the overall setup in ODA to receive event notifications for different conversation channels from external applications.
ODA Event Processing Architecture
ODA can consume external events of CloudEvents[1] specification via an inbound listening channel. The message after receipt can be processed in the ODA engine and sent out to any of the conversations channels that are supported by ODA platform. The high-level architecture diagram in Fig.1 describes the overall flow.
- A REST payload is sent from an external application to the ODA event listening channel
- After receiving the message, the ODA engine process it via the skills and posts the message content to one of the outbound conversation channels.

Fig. 1 ODA Event Processing Architecture
ODA Event Processing Flow
The triggering of an event from an external application creates a CloudEvents compatible message to be sent to the ODA listening channel. The high-level flow is illustrated in Fig. 2 as described in the ODA Documentation[2].

Fig. 2 ODA Event Processing Flow
ODA Event Processing Implementation
We provide an example of event processing by sending a REST payload message from an external client (Postman) to simulate the triggering of event in an external application. The use case here represents the automatic reminder message sent to the employees of a company when their certification for corporate compliance is about to expire for a certain course and they will have to retake it before a certain date.
The basic key components in building a skill to receive events and send notifications to a Twilio channel has been described in a blog[3] from the ODA PM team. The entire implementation here extends the same methodology and includes other notification delivery channels as listed below.
- MS-Teams
- Slack
- Test Channel
- Twilio
- Fusion Applications
- Custom Web Portal
The configuration is based on building a custom DA with a custom skill using Visual Flow Designer (VFD) and the basic flow for all the notification channels is the same as shown in Fig. 3. The only part which varies from one channel to another is the composition of the payload that is sent as part of the REST call from the external application. The next section discusses the payload structure and the significance of different fields in the payload as they apply to different channels.

Fig. 3 ODA Event Processing Implementation
Setup
A sample JSON payload used for the REST invoke from the external application is shown below.
{
"specversion": "1.0",
"type": "compliance.status",
"source": "externalCurl",
"id": "notify.user",
"time": "<timestamp of event trigger, e.g. 2024-05-01T21:19:24Z>",
"contenttype": "application/json",
"userid": "+<countrycode><Twilio_telephone_number, e.g. +19885551212>",
"channelname": "<Twilio_channel_name>, e.g. SL_Twilio",
"version": "2.0",
"data": {
"expirydate": "07-JUN-2024",
"coursename": "Annual Employee Compliance",
"courselink": "https://companylearning.com/course"
}
}
Table 1 below provides an explanation of each key field in the JSON payload and the significance of how it ties to the ODA configuration.
|
Key
|
Sample Value
|
ODA Implementation Notes
|
1
|
specversion
|
1.0
|
CloudEvents Spec Version
|
2
|
type
|
compliance.status
|
Application Event Name
|
3
|
source
|
externalCurl
|
Free Form Text String
|
4
|
id
|
notify.user
|
Notification Flow in Skill
|
5
|
time
|
2024-05-01T21:19:24Z
|
Timestamp of Event Trigger
|
6
|
contenttype
|
application/json
|
JSON payload sent to ODA
|
7
|
userid
|
+19885551212
|
Target Twilio number
|
8
|
channelname
|
SL_Twilio
|
Channel Name for Twilio
|
9
|
version
|
2.0
|
Application Event Version
|
10
|
data
|
{
expirydate: “07-JUN-2024”,
coursename: “Annual Employee Compliance”,
courselink: “https://companylearning.com/course”
}
|
Data fields as defined in the schema for Application Event
|
Table 1. REST Payload Details
The target URL and the header parameters for the REST call are described in Table 2 below.
|
Parameter
|
Sample value
|
ODA Implementation Notes
|
1
|
URL
|
https://<ODA_endpoint>/events/v2/listeners/appevent/channels/..
|
Event channel URL
|
2
|
Content-Type
|
application/cloudevents+json
|
CloudEvents spec
|
3
|
X-Hub SIgnature
|
Postman.setGlbalVariable(“hmac”, CryptoJS.HmacSHA256(request.data, “<Secret_Key>”)
|
Event Channel Secret
|
Table 2. REST Invoke Details
As we try to setup the ODA configuration for multiple delivery channels, the only two fields in the JSON payload that changes are listed below.
The value of channelname is the name of the channel configured in ODA console. The userid can be derived from the runtime value of the field ${system.message.userid}, which sometimes can be determined beforehand when they are constant for all user sessions. Fig. 4 below summarizes all the mapping correlations for the REST invoke.

Fig. 4 REST Call Mappings
Table 5 below highlights the nuances and specialties for the values of userid for various channels. This information could be useful for the Fusion Applications and few other channels, where the userid is dynamically set at runtime.
|
Channel
|
Sample value of ${system.message.userid} - userid
|
Same across multiple user sessions?
|
ODA Implementation Notes
|
1
|
Twilio
|
+19885551212
|
Not Applicable
|
Twilio target number
|
2
|
MS-Teams
|
Yes
|
Yes
|
Conversation ID from MS-Graph
|
3
|
Slack
|
W6J99..
|
Yes
|
Slack User Profile ID
|
4
|
Test Channel
|
4228104
|
No
|
System_Global_Test is the channelname
|
5
|
Fusion
|
300001569830_1854720A84G…
|
No
|
Userid_sessionID – set in webSDK
|
6
|
Custom WebSDK
|
ShubTest
|
Yes
|
Configured within the custom webSDK
|
Table 3. userid for various channels
Results
The entire setup was tested by sending the POST invoke from an external REST client like Postman and observing the messages that pop-up in the ODA user sessions for various channels. The notification message text was formatted by using the variable values sent in the data block of the JSON payload.
A curl command equivalent of the REST call sent from Postman is shown below. After a successful send of the command, an HTTP code of 202 is returned.
curl --location 'https://<…data.digitalassistant.oci.oraclecloud.com/events/v2/listeners/appevent/channels/592..>' \
--header 'Content-Type: application/cloudevents+json' \
--header 'X-Hub-Signature: sha256=<31ffeee….>' \
--data '{
"specversion": "1.0",
"type": "compliance.status",
"source": "externalCurl",
"id": "notify.user",
"time": "2024-05-01T21:19:24Z",
"contenttype": "application/json",
"userid": "+18882221313",
"channelname": "SL_Twilio",
"version": "2.0",
"data": {
"expirydate": "07-JUN-2024",
"coursename": "Annual Employee Compliance",
"courselink": "https://companylearning.com/course"
}
}'
Sample notification messages that appear in the ODA windows for Fusion Applications, Slack and MS-Teams channels are shown below in Fig. 5.

Fig. 5 Event Notification in ODA for Fusion Appplications, Slack and MS-Teams channels
Similar messages also appear in Twilio and Test channels as shown in Fig. 6.

Fig. 6 Event Notification in ODA for Twilio and Test channels
Acknowledgements
I would like to acknowledge the assistance I received from my teammate, Greg Mally in building the sample test cases for this blog. I would also like to thank Jobinesh Puroshothaman from ODA Engineering Team and Daniel Teixeira from ODA Product Management Team for their help at different times.
References
- CloudEvents Spec – GitHub for CloudEvents Information
- External Events in ODA - ODA Product Documentation
- The new Events channel enables a bot-initiated conversation! – Daniel Teixera, Oracle Blog from ODA Product Management