Interactive Canvas API reference

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.

Note: The interactiveCanvas object is attached to the window object. If you use a front-end framework to develop your web app, you must ensure that you have access to window to set up the API.

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.

Note: You must invoke the ready API in the web app as soon as the page is loaded. Otherwise, the Action closes.

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.

Caution: textQuery must be 640 characters or less.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

Determines the height of the header at the top of a display.

Parameters
height	number The height in pixels.

setCanvasState

setCanvasState(state): void

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.

Caution: The length of the string representation of the state object must be less than or equal to 50,000 characters. If the string exceeds 50,000 characters in length, an error is thrown.

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"/>.

Note: SSML marks are not invoked when the following occurs:

• Before TTS begins, the user taps the microphone, or the Interactive Canvas client invokes sendTextQuery. The TTS is cancelled and any SSML marks in the TTS are ignored.
• During TTS, the user taps the microphone, or the Interactive Canvas client invokes sendTextQuery. The TTS is interrupted and any remaining SSML marks in the TTS are ignored.

Parameters
markName	string Mark name invoked during TTS playback.