The Interactive Canvas API is a JavaScript library that you use to interface
with your Conversational Action using the interactiveCanvas
object in your web app.
For more information about Interactive Canvas, see the Interactive Canvas documentation .
Methods
ready
ready(callbacks) returns undefined
Called by the Interactive Canvas web app once it has loaded to register callbacks.
callbacks
InteractiveCanvasCallbacks
An object that contains method callbacks.
sendTextQuery
sendTextQuery(textQuery) returns Promise<state>
Sends a text query to the conversational action.
textQuery
string
The query to send to the conversational action.
state
string
One of the following:
READY:
Requests can be accepted by the platform.
BLOCKED:
There is a query in flight and the new query will be dropped.
UNKNOWN:
The current query state couldn't be determined.
getHeaderHeightPx
getHeaderHeightPx() returns Promise<height>
Determines the height of the header at the top of a display.
height
number
The height in pixels.
outputTts
outputTts(text, openMic) returns undefined;
Plays SSML text.
text
string
The SSML supported string to be played.
openMic
boolean
Whether to open mic after the TTS plays.
createIntentHandler
createIntentHandler(intentId, callback) returns IntentHandler
Creates an intent handler for an NLU custom intent.
intentId
string
Intent name as defined in Actions Builder.
callback
function( MatchedIntent
)
Function to be executed when the intent is matched.
object
Intent handler object that can be registered using expect()
.
IntentHandler
An object representing an intent handler. Can be registered using expect()
or prompt()
.
MatchedIntent
An object containing the data for a matched intent.
getIntentArg(parameterName)
function(string)
Method to get the intent parameter of a matched intent.
createNumberSlot
createNumberSlot(callback, hints?) returns Slot<number>
Creates a slot of type number.
callback
function( FilledSlot
)
Function to be executed when the slot is filled.
hints
Hints
Short words that the user might say when filling a slot. hints
help the NLU system decide which slot to fill.
createTextSlot
createTextSlot(callback, hints?) returns Slot<string>
Creates a slot of type string.
callback
function( FilledSlot
)
Function to be executed when the slot is filled.
hints
Hints
Short words that the user might say when filling a slot. hints
help the NLU system decide which slot to fill.
createConfirmationSlot
createConfirmationSlot(callback, hints?) returns Slot<boolean>
Creates a slot of type boolean.
callback
function( FilledSlot
)
Function to be executed when the slot is filled.
hints
Hints
Short words that the user might say when filling a slot. hints
help the NLU system decide which slot to fill.
createOptionsSlot
createOptionsSlot(options, callback, hints?) returns Slot<string>
Creates a slot from a pre-defined list of options.
options
array< Option
>
Function to be executed when the slot is filled.
callback
function( FilledSlot
)
Function to be executed when the slot is filled.
hints
Hints
Short words that the user might say when filling a slot. hints
help the NLU system decide which slot to fill.
Slot
An object representing a slot to be filled. Can be registered using expect()
or prompt()
.
FilledSlot<T>
An object representing a filled slot.
T
boolean|number|string
The slot type.
Option
An object representing a slot type entry.
key
string
The unique identifier for the slot type entry.
synonyms
array<string>
A list of words used to select the slot option.
Hints
An object representing hints for a slot.
associatedWords
array<string>
A list of words used to help the NLU system decide which slot to fill.
expect
expect(expectation) returns HandlerRegistration
Registers the expectation on the client. Can be called on intent handlers and slots.
expectation
IntentHandler
| Slot
The intent handler or slot to be registered.
object
The registered intent handler or slot.
HandlerRegistration
An object representing a registered intent handler.
deleteHandler()
function
Unregisters the expected intent handler.
clearExpectations
clearExpectations() returns undefined;
Removes all expectations by deleting all previously registered intent handlers and slots.
prompt
prompt(tts, expectation) returns Promise<Answer<T>>
Prompts the user with the provided TTS string, and registers the expectation on the client. Can be called on intent handlers and slots.
tts
string
The TTS string used to prompt the user for the provided expectation.
expectation
IntentHandler
| Slot
The intent handler or slot to be registered.
object
The user-supplied answer to the prompt.
Answer<T>
An object representing a user-supplied answer to a prompt.
value
boolean|number|string
The value of the user-supplied answer.
status
string
The answer status.
One of the following:
ANSWERED:
The user responded to the prompt with an answer.
NO_MATCH:
The user was prompted for an answer and responded with an answer that didn't match the expected answer or any other expected intent.
YIELD:
The user responded to the prompt with a different intent.
triggerScene
triggerScene(sceneName) returns Promise<TriggerSceneStatus>
Triggers a scene.
sceneName
string
The name of the scene to trigger.
TriggerSceneStatus
string
The status of the call to triggerScene().
One of the following:
SUCCESS:
The request was successfully processed by the server.
BLOCKED:
The request was blocked by an existing query in flight.
UNKNOWN:
The status of the request is unknown.
setUserParam
setUserParam(key, value) returns Promise<undefined>;
Sets the key-value pair that's passed and persisted between conversations.
key
string
The parameter key.
value
object|array|boolean|number|string
The parameter value.
getUserParam
getUserParam(key) returns Promise<object|array|boolean|number|string>;
Gets the param value for the given key if it exists and the status of the invocation.
key
string
The parameter key.
resetUserParam
resetUserParam() returns Promise<void>;
Clears all user parameters.
setHomeParam
setHomeParam(key, value) returns Promise<undefined>;
Sets the key-value pair that's passed and persisted between conversations.
key
string
The parameter key.
value
object|array|boolean|number|string
The parameter value.
getHomeParam
getHomeParam(key) returns Promise<object|array|boolean|number|string>;
Gets the param value for the given key if it exists and the status of the invocation.
key
string
The parameter key.
resetHomeParam
resetHomeParam() returns Promise<void>;
Clears all user parameters.
setCanvasState
setCanvasState(state) returns undefined
Notifies the Assistant that the Canvas web app has updated its state. The setCanvasState
method doesn't return a value. The state payload can be accessed through the conv.context.canvas.state
property.
state
Object
The updated state of the Canvas app as a JSON object.
InteractiveCanvasCallbacks
These callbacks provide a way for you to respond to information or requests from your Conversational Action while the methods provide a way to send information or requests to your Conversational Action.
onUpdate
onUpdate(data) returns Promise|undefined
Called when a Canvas
response is sent from the Conversational Action. TTS will start when
the returned Promise is resolved, or timeout after 10 seconds.
data
Object
Updated data sent by the webhook.
onTtsMark
onTtsMark(markName) returns undefined
Callback that is invoked during TTS playback.
Special marks that always are triggered:
-
STARTindicates the start of the TTS. -
ENDindicates the end of the TTS. -
ERRORindicates an error playing the TTS.
You can also define custom marks by using SSML
and the <mark>
tag, like <mark name="custom"/>
.
markName
string
Mark name invoked during TTS playback.
onInputStatusChanged
onInputStatusChanged(inputStatus) returns undefined
Notifies the Canvas app that the Assistant input status has changed.
inputStatus
Enum
Status of voice and/or text input processing on the device. Can be the following:
-
LISTENING: Microphone is open. -
IDLE: Microphone is closed. -
PROCESSING: Assistant is currently executing a query (microphone is closed).
