Learn how to embed a PlayAI Agent on your website
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.
openEmbed
FunctionThe 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
It has the following signature:
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”.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
.In this example, the openEmbed function is called inside a useEffect hook to initialize the web embed when the component mounts.
The events array defines the custom events that your application can handle. Each event in the array is an object with the following structure:
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
.The onEvent handler is a function that processes events triggered by the PlayAI web embed. It has the following signature:
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).In this example, the handler logs all events and updates the text state when a “change-text” event is received.
Here’s how these components work together:
This structure allows for flexible, event-driven interactions between your web application and the PlayAI web embed.