​

Functions and Events

Functions and events power your flows to interact with external systems and dynamically change Grace’s instructions based on the state of the system.

​

Events

Events are optional outputs of functions. A function may emit any one of a set of declared events. These events then cause state changes in the Flow, giving Grace new thoughts as the conversation progresses.

​

Functions

Functions are the core of how Grace is able to take actions on the outside world, they’re also useful for controlling conversational flow.

​

Creating a Function

You can create a function by clicking the “Create” button in the top right of the Functions page. This will bring up the create function page. Here you can configure your function, giving it a name, description, a set of inputs, declaring the outputs, and writing the javascript code that will be executed when the function is called.

​

Inputs

Functions can take in three types of inputs:

​

Parameters

Parameters are inputs that are passed in from Grace. For example, if you have a “search customer” function, you could pass in a customer name as a parameter.

​

Internal Parameters (Context Parameters)

Internal parameters are parameters that come from the context of the conversation. These may have been set by a previous function or may be a property of the current conversation.

​

Static Parameters

These are parameters configured per-flow. This can be secrets, such as API keys, or other “global” configuration such as API connection information.

​

Outputs

Functions return a single json object containing three properties, each of which has a separate use.

​

Response

The response is what Grace sees as the output of the function. This is the value that will be returned to Grace.

​

Context Additions

These are a set of key/value pairs that will be added to the context of the conversation. These can be used to store information that will be used by other functions, but does not need to be seen by Grace. It’s highly advised you list all the potential context addition keys under “Emitted Context Additions” so that the UI can offer smart suggestions. A warning will be emitted if a function adds context that is not declared.

​

Events.

Finally, events are what drive changes in state in a flow. A function may emit zero or one events. It’s highly advised you list all the potential events under “Emitted Events” so that the UI can offer smart suggestions. A warning will be emitted if a function emits an event that is not declared.

​

Source Code

The source code is the JavaScript code that will be executed when the function is called. There is a full reference of all the available helpers in the app under the info icon.

​

Using Functions

Functions can be called directly by Grace, called automatically at the conversation’s start, or called automatically at the conversation’s end. In order for Grace to use a function, the flow must have visited a state where that function was available.

Functions remain available even after the conversation state has changed.

You can add a function to a state by selecting the state, going to the “Functions” tab, and adding the desired function to the state.

​

Designing Functions

Not all functions need to “do things”, sometimes it’s useful to have a function that emits an event that causes the conversation to enter a new state For example, if there are complex rules around billing, you probably do not want to include all that logic in the initial state. Instead one should have a function called “start billing process” that emits an event that causes the conversation to enter the new state with detailed billing instructions.