Skip to main content
In just a few minutes, you’ll learn how to add powerful AI chat capabilities to enhance your user experience. You can set up the agent with a pathway ID or use a agent prompt. To get started with creating a widget, head over to our Bland Dashboard.

​
Installation

You can create a web widget via the API, or through the dashboard. Once you’ve created your widget, you should have an ID which you can pass into the following code snippet: 
<script>
  window.blandSettings = {
    widget_id: "b5f3fb6b-2285-4c73-95be-6609eca09986", // Replace with your widget ID
  };
</script>
<script src="https://widget.bland.ai/loader.js" defer></script>
Once you’ve added this code snippet to the <head> of your website, you should see the chat widget load. You can customize the widgets appearance via the config property, or by using our visual editor on the platform. Here is a quick video tutorial of how to create and configure a new web widget on the platform: Passing Additional Data (Optional) You can pass custom data to your widget at initialization using the request_data setting. This is useful for personalizing conversations with user information: 
<script>
  window.blandSettings = {
    widget_id: "b5f3fb6b-2285-4c73-95be-6609eca09986",
    request_data: {
      user_id: "12345",
      first_name: "John",
      last_name: "Doe",
    },
  };
</script>
<script src="https://widget.bland.ai/loader.js" defer></script>
Now this information will be available to your agent as variables.

​
Advanced: Custom Components

When using pathways in your widget, you can create custom components that display at specific points in the conversation. These components are embedded as iframes within the widget window.

​
Passing data to custom components

You can send agent variables to your custom components to personalize the user experience. These variables are passed as query parameters to your iframe URL. Setting up variables: Define which variables to pass in one of two ways: Accessing variables in your component: The variables are automatically appended as query parameters to your component’s URL. You can access these variables using standard JavaScript: 
// Example: Retrieving and displaying the user's first name
const params = new URLSearchParams(window.location.search);
const firstName = params.get("firstName");

// Use the variable to personalize your component
document.getElementById("greeting").textContent = `Hello, ${firstName}!`;

​
Creating Interactive Custom Components

Your custom component can send messages back to the widget using window events. Example: Creating a button that sends a message 
// This code snippet is on the webpage of the custom component
<button onclick="parent.window.postMessage('widget-message:Hello World!', '*')">
  Send Message
</button>
Note: All messages must be prefixed with widget-message:. The text after this prefix becomes the user message content. For example, an event widget-message:Hello World! will create a user message with the content “Hello World!”. widget-message:Option A selected will create a user message with the content “Option A selected”.

​
Widget Bland Settings Options

The chat widget can be customized using the following configuration options:
OptionTypeDefaultDescription
widget_idstringRequiredThe ID of the widget you want to use on your website
request_datastring-A record of variables you want to pass to the agent
⌘I