Interactive Canvas API reference

  • The Interactive Canvas API is a JavaScript library used to interface with a Conversational Action via the interactiveCanvas object in a web app.

  • The ready method must be invoked when the web app loads to register callbacks, otherwise the Action will close.

  • The sendTextQuery method sends a text query to the conversational action, with a maximum length of 640 characters.

  • The onUpdate callback is triggered when a Canvas response is sent from the Conversational Action, and TTS starts after the returned Promise is resolved or times out.

  • The onTtsMark callback is invoked during TTS playback, including special marks for start, end, and error, and supports custom marks using SSML.

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.

Parameters
callbacks InteractiveCanvasCallbacks

An object that contains method callbacks.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Sends a text query to the conversational action.

Parameters
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.

Parameters
height number

The height in pixels.

outputTts

outputTts(text, openMic) returns undefined;

Plays SSML text.

Parameters
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.

Parameters
intentId string

Intent name as defined in Actions Builder.
callback function(MatchedIntent)

Function to be executed when the intent is matched.
IntentHandler 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.

Methods
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.

Parameters
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 object

Slot object that can be registered using prompt().

createTextSlot

createTextSlot(callback, hints?) returns Slot<string>

Creates a slot of type string.

Parameters
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 object

Slot object that can be registered using prompt().

createConfirmationSlot

createConfirmationSlot(callback, hints?) returns Slot<boolean>

Creates a slot of type boolean.

Parameters
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 object

Slot object that can be registered using prompt().

createOptionsSlot

createOptionsSlot(options, callback, hints?) returns Slot<string>

Creates a slot from a pre-defined list of options.

Parameters
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 object

Slot object that can be registered using prompt().

Slot

An object representing a slot to be filled. Can be registered using expect() or prompt().

FilledSlot<T>

An object representing a filled slot.

Parameter
T boolean|number|string

The slot type.

Option

An object representing a slot type entry.

Fields
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.

Fields
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.

Parameters
expectation IntentHandler|Slot

The intent handler or slot to be registered.
HandlerRegistration object

The registered intent handler or slot.

HandlerRegistration

An object representing a registered intent handler.

Methods
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.

Parameters
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.
Answer<T> object

The user-supplied answer to the prompt.

Answer<T>

An object representing a user-supplied answer to a prompt.

Fields
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.

Parameters
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.

Parameters
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.

Parameters
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.

Parameters
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.

Parameters
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.

Parameters
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.

Parameters
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:

  • START indicates the start of the TTS.
  • END indicates the end of the TTS.
  • ERROR indicates an error playing the TTS.

You can also define custom marks by using SSML and the <mark> tag, like <mark name="custom"/>.

Parameters
markName string

Mark name invoked during TTS playback.

onInputStatusChanged

onInputStatusChanged(inputStatus) returns undefined

Notifies the Canvas app that the Assistant input status has changed.

Parameters
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).