Web Embed API

This document provides detailed information about the key components of the play.ai web embed API: the events array, the onEvent handler, and the openEmbed function.

​

Installation

npm install @play-ai/web-embed

​

openEmbed Function

The openEmbed function initializes and opens the play.ai web embed on the webpage. It is imported from the @play-ai/web-embed package as follows

import { open as openEmbed } from '@play-ai/web-embed';

It has the following signature:

function openEmbed(
  webEmbedId: string,
  options: {
    events?: ReadonlyArray<Event>;
    onEvent?: OnEventHandler;
    prompt?: string;
    customGreeting?: string;
  },
): { setMinimized: (minimize?: boolean) => void };

​

Parameters

• webEmbedId: A string representing your unique web embed ID provided by play.ai.
• options: An object containing:
  • events?: The array of custom events your application can handle.
  • onEvent?: The event handler function.
  • customGreeting?: A custom greeting that replaces the default greeting.
  • prompt?: A prompt to give the agent in addition to the default prompt. Use this to give context that is page-specific or user-specific, e.g. “The form fields on the current page are X, Y, and Z”.

​

Return type

• setMinimized(minimize?: boolean): A function that allows you to toggle the minimized state of the web embed. Pass in true to minimize and false to maximize the web embed. Toggle the minimize state by passing in undefined.

​

Example

import { open as openEmbed } from '@play-ai/web-embed';

// ... (events and onEvent definitions) ...

useEffect(() => {
  const { setMinimized } = openEmbed(webEmbedId, {
    events,
    onEvent,
    customGreeting: "Let's fill out this form together!",
    prompt: 'The form fields on the current page are name, email, and shipping address',
  });
}, []);

In this example, the openEmbed function is called inside a useEffect hook to initialize the web embed when the component mounts.

​

Events Array

The events array defines the custom events that your application can handle. Each event in the array is an object with the following structure:

type Event = {
  name: string;
  when: string;
  data: {
    [key: string]: {
      type: string;
      description?: string;
      values?: string[];
    };
  };
};

​

Properties

• name: A string that uniquely identifies the event.
• when: A string describing the condition that triggers this event.
• data: An object describing the data that should be passed to the event handler. Each key in this object represents the name of the data field, and its value is an object with:
  • type: The data type of the field (currently supports string, number, boolean, and enum).
  • description?: A brief description of what this data field represents.
  • values?: An array of strings representing the possible values for the field if the type is enum.

​

Example

const events = [
  {
    name: "change-text",
    when: "The user says what they want to change the text on the screen to",
    data: {
      text: { type: "string", description: "The text to change to" },
    },
  },
] as const;

​

onEvent Handler

The onEvent handler is a function that processes events triggered by the play.ai web embed. It has the following signature:

type OnEventHandler = (event: { name: string; data: Record<string, any> }) => void;

​

Parameters

• event: An object containing:
  • name: The name of the triggered event (matching an event name from the events array).
  • data: An object containing the data associated with the event (matching the data structure from the events array).

​

Example

const onEvent = (event) => {
  console.log('onEvent: ', event);
  if (event.name === 'change-text') {
    setText(event.data.text);
  }
};

In this example, the handler logs all events and updates the text state when a “change-text” event is received.

​

Putting It All Together

Here’s how these components work together:

1. You define your custom events in the events array.
2. You implement the onEvent handler to process these events.
3. You call the openEmbed function, passing your web embed ID, the events array, the onEvent handler, and optionally customGreeting and prompt.
4. When a user interacts with the AI agent, it may trigger one of your defined events.
5. The onEvent handler receives the triggered event and processes it according to your implementation.

This structure allows for flexible, event-driven interactions between your web application and the play.ai web embed.

Learn more about how to use the web embed API in this guide.