# 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]
> **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](https://developers.google.com/assistant/interactivecanvas).

## Methods

<br />

> [!WARNING]
> **Warning**: Some of the Interactive Canvas APIs are currently in Developer Preview. You can test the APIs in the simulator, but do not deploy an Action that use these features to alpha, beta, or production channels. Actions deployed using these features will not function on end-user devices.

<br />

### ready

    ready(callbacks) returns undefined

Called by the Interactive Canvas web app once it has loaded to register callbacks.

| Parameters ||
|---|---|
| `callbacks` | ` https://developers.google.com/assistant/interactivecanvas/reference#interactivecanvascallbacks ` An object that contains method callbacks. |

> [!NOTE]
> **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. <br /> |

> [!CAUTION]
> **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. |

### 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

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    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(https://developers.google.com/assistant/interactivecanvas/reference#matchedintent)` Function to be executed when the intent is matched. |
| `https://developers.google.com/assistant/interactivecanvas/reference#intenthandler` | `object` Intent handler object that can be registered using `https://developers.google.com/assistant/interactivecanvas/reference#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

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    createNumberSlot(callback, hints?) returns Slot<number>

Creates a slot of type number.

| Parameters ||
|---|---|
| `callback` | `function(https://developers.google.com/assistant/interactivecanvas/reference#filledslott)` Function to be executed when the slot is filled. |
| `hints` | `https://developers.google.com/assistant/interactivecanvas/reference#hints` Short words that the user might say when filling a slot. `hints` help the NLU system decide which slot to fill. |
| `https://developers.google.com/assistant/interactivecanvas/reference#slot` | `object` Slot object that can be registered using `https://developers.google.com/assistant/interactivecanvas/reference#prompt`. |

### createTextSlot

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

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

Creates a slot of type string.

| Parameters ||
|---|---|
| `callback` | `function(https://developers.google.com/assistant/interactivecanvas/reference#filledslott)` Function to be executed when the slot is filled. |
| `hints` | `https://developers.google.com/assistant/interactivecanvas/reference#hints` Short words that the user might say when filling a slot. `hints` help the NLU system decide which slot to fill. |
| `https://developers.google.com/assistant/interactivecanvas/reference#slot` | `object` Slot object that can be registered using `https://developers.google.com/assistant/interactivecanvas/reference#prompt`. |

### createConfirmationSlot

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

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

Creates a slot of type boolean.

| Parameters ||
|---|---|
| `callback` | `function(https://developers.google.com/assistant/interactivecanvas/reference#filledslott)` Function to be executed when the slot is filled. |
| `hints` | `https://developers.google.com/assistant/interactivecanvas/reference#hints` Short words that the user might say when filling a slot. `hints` help the NLU system decide which slot to fill. |
| `https://developers.google.com/assistant/interactivecanvas/reference#slot` | `object` Slot object that can be registered using `https://developers.google.com/assistant/interactivecanvas/reference#prompt`. |

### createOptionsSlot

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

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

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

| Parameters ||
|---|---|
| `options` | `array<https://developers.google.com/assistant/interactivecanvas/reference#option>` Function to be executed when the slot is filled. |
| `callback` | `function(https://developers.google.com/assistant/interactivecanvas/reference#filledslott)` Function to be executed when the slot is filled. |
| `hints` | `https://developers.google.com/assistant/interactivecanvas/reference#hints` Short words that the user might say when filling a slot. `hints` help the NLU system decide which slot to fill. |
| `https://developers.google.com/assistant/interactivecanvas/reference#slot` | `object` Slot object that can be registered using `https://developers.google.com/assistant/interactivecanvas/reference#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

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    expect(expectation) returns HandlerRegistration

Registers the expectation on the client. Can be called on intent handlers and slots.

| Parameters ||
|---|---|
| `expectation` | `https://developers.google.com/assistant/interactivecanvas/reference#intenthandler|https://developers.google.com/assistant/interactivecanvas/reference#slot` The intent handler or slot to be registered. |
| `https://developers.google.com/assistant/interactivecanvas/reference#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

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    clearExpectations() returns undefined;

Removes all expectations by deleting all previously registered intent handlers and slots.

### prompt

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    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` | `https://developers.google.com/assistant/interactivecanvas/reference#intenthandler|https://developers.google.com/assistant/interactivecanvas/reference#slot` The intent handler or slot to be registered. |
| `https://developers.google.com/assistant/interactivecanvas/reference#answert` | `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. <br /> |

### triggerScene

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

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

### setUserParam

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    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

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    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

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    resetUserParam() returns Promise<void>;

Clears all user parameters.

### setHomeParam

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    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

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    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

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

    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`](https://developers.google.com/assistant/interactivecanvas/web-apps#setcanvasstate)
method doesn't return a value. The state payload can be accessed through the
[`conv.context.canvas.state`](https://actions-on-google.github.io/assistant-conversation-nodejs/3.1.0/interfaces/_api_schema_.context.html) property.

> [!CAUTION]
> **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](https://developers.google.com/assistant/conversational/ssml) and the `<mark>` tag, like
`<mark name="custom"/>`.

> [!NOTE]
> **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. |

### onInputStatusChanged

<br />

> [!CAUTION]
> **Caution**: This API is currently in Developer Preview. You can test this API in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using this feature will not function on end-user devices.

<br />

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