Skip to main content
Embed SDK is available only to paid plans.

Overview

Our Embed SDK lets you interact with TeamAI chatbots embedded on your web pages. It provides methods to update context and retrieve current context, giving you full control over your embedded chatbots.
If you embedded your chatbot before September 29, 2024, you may need to update the embed code on your website. The new embed code now includes the Embed SDK automatically.
To use the Embed SDK, ensure that you have the correct assistant ID and the appropriate plan.

Embed Data Attributes

You can control the appearance and behavior of your embedded chatbot by adding data attributes to the embed <div>. Here are the supported attributes:
AttributeDescriptionExample Value
data-chatbot-id(Required) The unique identifier for your chatbot instance."YOUR_ASSISTANT_ID"
data-chatbot-modeDisplay mode: "standard" (default) or "popover" for a floating bubble."popover"
data-hide-headerHide the agent header (avatar, title, clear button) if set to "true"."true"
data-button-colorBackground color for the chat bubble button (popover mode only)."#007bff"
data-icon-colorIcon color for the chat bubble button (popover mode only)."#fff"
Example:

Methods

Initialize Embed SDK

The SDK automatically initializes when the chatbot is embedded on your page. You don’t need to call an explicit init function.

Get Chatbot Instance

Retrieves an instance of the chatbot for interaction.
assistantId
string
required
The unique identifier for your chatbot instance.
This method returns a chatbot instance that you can use to interact with your embedded chatbot.

Wait for Chatbot Ready State

Update Chatbot Context

Updates the context for your chatbot.
newContext
object
required
The new context data to update the chatbot with.
This method allows you to update the context for the chatbot dynamically. You can use these context variables in your assistant’s instructions like so: {{userEmail}}.

Get Chatbot Context

Retrieves the current context of the chatbot.
This method returns the current context of the chatbot.

Get Conversation History

Retrieves the complete conversation history between the user and the chatbot.
This method returns a Promise that resolves to an object containing the conversation history. The returned object has the following structure:

Example: Retrieve and Display Conversation History

This method is useful for analytics, saving conversation logs, or implementing custom conversation displays.

Reset Conversation

Resets the conversation with the chatbot, clearing the chat history and starting fresh.
This method returns a Promise that resolves when the conversation has been successfully reset. It’s useful for implementing a “Start Over” or “New Chat” button in your interface.

Example: Adding a Reset Button

Register Client-side Tools

Register custom tools that your chatbot can execute on the client side. This allows your chatbot to interact with the user’s browser environment.
tool
object
required
name
string
required
The name of the tool, which the chatbot will use to call it.
description
string
required
A description of what the tool does.
parameters
object
required
The parameters the tool accepts (similar to OpenAI function schema).
execute
function
required
A function that will be called when the chatbot uses this tool. It receives the parameters provided by the chatbot and should return a result.

Unregister Client-side Tools

Remove a previously registered client-side tool.
toolName
string
required
The name of the tool to unregister.

Get Registered Tools

Retrieve a list of all currently registered client-side tools.

Multi-Agent Events

When your chatbot uses multi-agent orchestration (specialist agents for specific tasks), you can listen to events for enhanced user experience and tracking.

Listen for Agent Handoffs

Called when the main agent delegates a task to a specialist agent.
callback
function
required
Function to call when an agent handoff occurs. Receives an object with targetAgentId, targetAgentName, task, and reason.

Listen for Specialist Returns

Called when a specialist agent completes its task and returns control to the main agent.
callback
function
required
Function to call when a specialist returns to the main agent. Receives an object with task results and completion details.

How Multi-Agent Orchestration Works

  1. Task Analysis: The main agent analyzes the user’s request
  2. Specialist Selection: If specialized knowledge is needed, the main agent selects an appropriate specialist
  3. Task Handoff: The main agent hands off the specific task to the specialist
  4. Specialist Processing: The specialist agent handles the task with its specialized knowledge
  5. Result Integration: The specialist returns results to the main agent
  6. Unified Response: The main agent presents the final response to the user

Hidden Messages

During multi-agent orchestration, internal coordination messages between agents are automatically hidden from the user interface to maintain a seamless experience. Users only see the relevant parts of the conversation.

Example: Multi-Agent Integration

Upload Data

Uploads a file (e.g., a CSV or text file) to your chatbot so you can query that data directly within the conversation. Once uploaded, the chatbot will have immediate access to the file contents. If you attempt to upload the same file again, the SDK will detect a matching file fingerprint and re-use the previous upload — so you won’t need to re-upload duplicates.
myFile
Blob
required
A Blob or File object. Currently, only CSV-formatted files are supported.

Example: Updating Context

In this example, we’re setting up the chatbot and updating the context with the user’s email and name.
This example demonstrates how to set up the chatbot, log its readiness, and update its context programmatically.

Example: Chat with a CSV or Excel file

Upload your CSV file to let your chatbot parse and answer questions about it.

Example: Add Client-side Tools

This example shows how to register client-side tools that allow your chatbot to interact with the user’s browser.

Debug Mode

To enable debug mode in TeamAI, add ?teamAIDebug=true to your app’s URL. For example, if you’ve embedded your TeamAI instance in your app hosted at https://example.com, you can activate debug mode by changing the URL to:
After adding this parameter, refresh the page and open your browser’s developer console (usually by pressing F12 or right-clicking and selecting “Inspect” then navigating to the “Console” tab).