Embedding an Agent on your Website

​

Introduction

The play.ai web embed allows you to integrate AI-powered interactions into your web application. This guide will walk you through the process of setting up and using the play.ai web embed in your React application.

​

Installation

First, install the @play-ai/web-embed package:

npm install @play-ai/web-embed

​

Basic Usage

Here’s a step-by-step guide to implement the play.ai web embed in your React application:

1

Create an agent

If you haven’t already, create an agent on https://play.ai.

2

Import the necessary dependencies

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

3

Define your web embed ID

const webEmbedId = 'YOUR_WEB_EMBED_ID';

Replace YOUR_WEB_EMBED_ID with the actual ID provided by play.ai, which can be found in the Agent editor.

Find your web embed ID on the last page of the Agent editor under 'Deploy Web'

4

Define custom events (optional)

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;

Custom events are optional, but they allow you to define custom behavior for your agent, to allow it to execute javascript and interact with the page. Learn more about custom events here.

This example defines a single event called “change-text” that will be triggered when the user specifies the text they want to display.

5

Implement the custom event handler (optional)

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

If you define custom events, you must implement an event handler to handle the events. Learn more about the custom event handler here.

This handler logs the event and updates the text state when a “change-text” event is received.

6

Initialize the web embed

useEffect(() => {
  openEmbed(webEmbedId, { events, onEvent });
}, []);

This useEffect hook initializes the web embed when the component mounts. See all the parameters that can be passed to openEmbed() here.

7

Render the component

return (
  <>
    <div className="flex justify-center items-center h-[70vh]">
      <div className="font-medium text-2xl">{text}</div>
    </div>
  </>
);

This example renders the current text in the center of the page.

​

Full Example

Here’s the complete example of a React component using the play.ai web embed.

"use client";
import { useEffect, useState } from "react";
import { open as openEmbed } from "@play-ai/web-embed";

const webEmbedId = "YOUR_WEB_EMBED_ID";

export default function Home() {
  const [text, setText] = useState("Change this text");

  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;

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

  useEffect(() => {
    openEmbed(webEmbedId, { events, onEvent });
  }, []);

  return (
    <>
      <div className="flex justify-center items-center h-[70vh]">
        <div className="font-medium text-2xl">{text}</div>
      </div>
    </>
  );
}

View the live example here.

View the code here.

​

Customization

You can customize the behavior of your AI agent by modifying the agent greeting and prompt. In this example, the agent is instructed to change the text on the page and end the call immediately after doing so.

The greeting and prompt for the Change Text demo agent

​

Other examples

• View other examples

​

Conclusion

This guide demonstrates how to integrate the play.ai web embed into your React application. You can extend this functionality by adding more events and customizing the agent’s behavior to suit your specific needs.

​

Next Steps

• Learn more about custom events