Overview - TeamAI Docs

The Embed SDK is available on paid plans.

What you can build with it

Embedding a TeamAI agent puts a chat window on your site. The Embed SDK makes that window part of your product. Your page can tell the agent who the visitor is, start the conversation at the right moment, and let the agent act inside your app.

Goal	What the SDK gives you
Answers that fit the visitor	`updateContext()` passes plan, page, cart, or account details for the agent’s instructions.
Conversations that follow a signed-in customer across devices	`identify()` ties the chat to your user ID and creates a contact in your workspace.
Proactive help instead of an idle bubble	`sendMessage()` opens with a question or task when the visitor lands, clicks, or gets stuck.
An agent that does things in your app	`registerTool()` lets the agent look up an order, navigate, or fill a form through your code.
Analysis of the visitor’s own data	`uploadBlob()` hands the agent a CSV from your page.
A UI that reacts to the agent	`thinking`, `answering`, and `answerComplete` events drive spinners, buttons, and next steps.

What teams ship with this:

A pricing page where the agent opens with “You are on the Pro plan. Want to see what Enterprise adds?”
A support portal where the agent pulls the customer’s open tickets before answering.
A dashboard where a visitor uploads an export and asks questions about it.

How it works

The embed code is one <div> and one <script>. The script renders your agent inside an iframe served from app.teamai.com and exposes a global object, tai, on your page. Every method below is called on an agent instance you get from tai. Your page and the iframe talk over postMessage. The SDK only accepts replies from the iframe it created, and the iframe only accepts commands from the page that embeds it, so a third-party script on your page cannot drive the chat.

If you embedded your agent before September 29, 2024, replace the embed code on your website. The current embed code loads the SDK automatically.

Get the embed code

In TeamAI, open the agent you want to embed.
Open the Channels tab and select Website.
Choose the Scripts option. The iframe option renders the chat but does not load the SDK.
Copy the snippet. It looks like this:

<div data-chatbot-id="YOUR_ASSISTANT_ID" data-chatbot-mode="popover"></div>
<script src="https://app.teamai.com/chatbot-embed.js" defer></script>

The value of data-chatbot-id is the assistant ID. Every SDK call takes it as the first argument. If you plan to upload files with the SDK, create an embed key on the same Channels page and add it as data-chatbot-embed-key. See File uploads.

Embed attributes

Set these on the <div>. The script reads them once, when it initializes the agent.

Attribute	Required	Values
`data-chatbot-id`	Yes	The assistant ID.
`data-chatbot-mode`	No	`standard` (default) renders inline and fills the div. `popover` renders a floating button that opens a 400px by 640px panel.
`data-chatbot-embed-key`	No	A publishable embed key. Required for `uploadBlob()`. Safe to ship in frontend code.
`data-hide-header`	No	`"true"` hides the header (avatar, title, clear button) inside the chat.
`data-button-color`	No	Background color of the popover button. Default `black`.
`data-icon-color`	No	Icon color of the popover button. Default `white`.

<div
  data-chatbot-id="YOUR_ASSISTANT_ID"
  data-chatbot-mode="popover"
  data-chatbot-embed-key="YOUR_PUBLISHABLE_EMBED_KEY"
  data-hide-header="true"
  data-button-color="#007bff"
  data-icon-color="#fff"></div>
<script src="https://app.teamai.com/chatbot-embed.js" defer></script>

In standard mode the iframe is width: 100%; height: 100%; min-height: 700px, so give the div a height. In popover mode the button and panel are position: fixed in the bottom-right corner, and the div’s position does not matter. You can embed several agents on one page. Add one div per assistant and load the script once.

Quickstart

This page passes the visitor’s plan to the agent, sends a first message, and re-enables a button when the answer finishes.

<button id="ask" disabled>Ask about my plan</button>

<div data-chatbot-id="YOUR_ASSISTANT_ID" data-chatbot-mode="standard" style="height: 700px"></div>
<script src="https://app.teamai.com/chatbot-embed.js" defer></script>

<script>
  window.addEventListener("teamAIChatbotReady", () => {
    const chatbot = tai.getInstance("YOUR_ASSISTANT_ID");
    const button = document.getElementById("ask");

    // Available in the agent's instructions as {{plan}}
    chatbot.updateContext({ plan: "Pro" });

    chatbot.onAnswerComplete(() => {
      button.disabled = false;
    });

    button.addEventListener("click", async () => {
      button.disabled = true;
      const result = await chatbot.sendMessage("What does my plan include?");
      if (!result.success) {
        console.warn(result.code, result.message);
        button.disabled = false;
      }
    });

    button.disabled = false;
  });
</script>

Register the teamAIChatbotReady listener before the embed script runs. With defer, an inline script placed anywhere in the document runs first.

Readiness has three stages

Each stage unlocks different calls.

Stage	How you know	What works
Script loaded	`window.tai` is defined.	`tai.getInstance()`. The instance exists but the iframe may not have loaded.
Agent ready	`teamAIChatbotReady` fires, or `await chatbot.ready()` resolves.	`updateContext()`, `registerTool()`, `identify()`, `sendMessage()`, `uploadBlob()`, `resetConversation()`.
Conversation ready	`await chatbot.conversationReady()` resolves.	`getConversation()` returns the restored history instead of an empty list.

teamAIChatbotReady fires once, after every agent on the page has reached the ready stage. Its event.detail.chatbots is a Map of assistant ID to instance. sendMessage() waits for the conversation stage on its own, and for any in-progress identify() verification, so you do not need to call conversationReady() before sending. You do need it before getConversation(), because getConversation() reads whatever the iframe is showing at that moment.

tai.getInstance(id) creates an instance for any ID you pass, even one that is not on the page. If the ID has a typo, ready() never resolves and sendMessage() returns timeout after 35 seconds. Copy the ID from the Channels page.

Context variables

updateContext() merges an object into the agent’s context. Reference any key in the agent’s instructions as {{key}}, for example {{userEmail}}. The SDK sends the current context with every request, so a value updated between messages applies to the next message.

Updating context from the page

Single-page applications

The embed script scans the document once, when it loads. A div rendered later is not picked up automatically.

// After your framework mounts the div
const element = document.querySelector('[data-chatbot-id="YOUR_ASSISTANT_ID"]');
const chatbot = tai.getInstance("YOUR_ASSISTANT_ID");
chatbot.initializeChatbot(element);
await chatbot.ready();

// When the view unmounts
tai.destroyInstance("YOUR_ASSISTANT_ID");

Do not call tai.initializeAll() a second time. It re-initializes every div on the page and appends a second iframe to agents that already have one. destroyInstance() removes the iframe and button, drops all listeners, settles any pending sendMessage() calls with code: "destroyed", and clears the upload cache for that assistant.

Next steps

Messages and status: send messages, handle busy, follow the answer.
API reference: every method, parameter, and return type.
Client-side tools: let the agent call functions in your page.
File uploads: give the agent a CSV or other file from your page.
Identity verification: attach the chat to a signed-in user.
Troubleshooting: debug mode and common failures.

​What you can build with it

​How it works

​Get the embed code

​Embed attributes

​Quickstart

​Readiness has three stages

​Context variables

​Single-page applications

​Next steps

What you can build with it

How it works

Get the embed code

Embed attributes

Quickstart

Readiness has three stages

Context variables

Single-page applications

Next steps