This document provides detailed information about the key components of the PlayAI web embed API: the events array, the onEvent handler, and the openEmbed function.
Looking for a tutorial? Check out our web embed tutorial.

​
Installation

npm install @play-ai/agent-web-sdk

​
openEmbed Function

The openEmbed function initializes and opens the PlayAI web embed on the webpage. It is imported from the @play-ai/agent-web-sdk package as follows 
import { open as openEmbed } from '@play-ai/agent-web-sdk';
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 PlayAI.
  • 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/agent-web-sdk';

// ... (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 PlayAI 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 PlayAI web embed.