How to Use Trigger Event Action?

Trigger event action (link to actions in widget page here) can be a great way to retrieve data that cannot be fetched by an API call action in the widget or to perform non-trivial computations.

Specifically, trigger event action allows you to execute some javascript you provide on a page where the widget is embedded, and consume return values for further use in the widget (as context variables).

To use it, you should do the following

1. Reach out

Ask your Forethought representative to enable trigger action for you to get started. You can additionally reach us at support@forethought.ai

2. Add Trigger Event to Intent

• Add Trigger Event to workflow canvas
  • Click Add Action
  • Drag Trigger Event Action onto workflow canvas
• Give Trigger Event an Event Name and select which context variables you wish to update the conversation with after the event

• Save Trigger Event and publish workflow changes

3. Listening to Trigger Event

• Use addEventListener() to listen to MessageEvent events
• Add logic to check for the Event Name that you gave the Trigger Event in step
  

window.addEventListener('message', (e) => {
 if (e.data.event === 'forethoughtTriggerEventAction') {
  switch (e.data.name) {
   case 'Trigger Event Example':
    // do whatever is needed here 
    // update the conversation as documented in Step 3 
    break; 
   } 
 } 
})

window.addEventListener('message', ({ data }) => {
 if (data.event === 'forethoughtTriggerEventAction') {
  switch (data.name) {
   case 'Trigger Event Example': 
    // do whatever is needed 
   break; 
  default: 
  } 
 } 
})

• the MessageEvent data property will look like:

{ 
 // Non configurable data that we provide for all events 
 "additionalContext": { 
    // user query if any that triggered the inten 
    "free_form_query": "trigger event" 
  }, 
  // Event will always be "forethoughtTriggerEventAction" 
  "event": "forethoughtTriggerEventAction", 
  // A list of the context variables you said you would update 
  "expectedContextVariables": [
   "First Name", 
   "Last Name" 
  ], 
  // The Event Name you gave this Trigger Event 
 "name": "Trigger Event Example" 
}

additionalContext will have access to majority of the context variables that conversation has.

4. Update the conversation

• The conversation will remain paused until the following API is executed

window.Forethought(
 'widget', 
 'triggerEventComplete', 
{ 
  // identifer is the Event Name and has to match what we are expecting 
  identifier: 'Trigger Event Example', 
  // payload contains values for all the context variables you said you were going to update 
  payload: {'First Name': 'Forethought', 'Last Name': 'AI'}, 
 } 
)

Example Use Cases

1. If you use a custom authentication mechanism that is not covered by Forethoughts API call action, you can use a trigger event to make the necessary call yourself and pass back the return values.

2. If you received a complicated return from an API call action, and need to perform a complicated logic with it (such as comparing dates), you can run that logic using trigger event, and pass back the response value.

Note that you can have multiple different trigger events in the same workflow.