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
default_chatbooleanfalseIf true, the widget will open on the chat by default instead of the channel menu
visitor_idstring-Use a custom visitor ID to identify the user vs the default cookie based visitor ID, which expires after 1 week
enable_widget_state_eventsbooleanfalseEmits bland_widget_state_change window events on open/close/resize, enabling parent page coordination in embedded setups
draggablebooleanfalseIf true, the widget button will be draggable

​
Escalate to Live Agents

This feature only works on pathways.
Connect your Bland widget to any live agent platform (Zendesk, Intercom, Freshdesk, or your own custom solution) via webhooks. When the AI determines a human is needed, it seamlessly hands off the conversation with full context.

​
Setup

1

Configure the Pathway Transfer Node

In your pathway, add a Pathway Transfer Node and select Live Agent Transfer as the transfer type. Enter the webhook URL where Bland should send conversation data.
2

Enable Webhook Signing

Webhook signing is required for this integration. Bland signs all webhook payloads with HMAC, sent via the X-Bland-Signature header. Use your signing secret to verify requests originate from Bland and haven’t been tampered with.See Webhook Signing for implementation details.
3

Handle Incoming Webhooks

Your endpoint will receive two types of payloads from Bland: the initial conversation handoff, and subsequent user messages.
4

Send Messages Back to the User

Use the Send Live Agent Message endpoint to send responses from your live agent to the user. When the conversation is complete, send an END_CONVERSATION payload to close the session.

​
Webhook Payloads

​
INITIAL_CONVERSATION

Sent when the transfer is triggered. Contains the full conversation history and all agent variables. 
{
  "type": "INITIAL_CONVERSATION",
  "thread_id": "0e96f65a-244b-45c9-9342-487f548195dd",
  "sender_id": "ec14ee83-fa2b-493a-b009-0e29414a1e97",
  "language": "es",
  "variables": {
    "now_utc": "Wednesday, December 10, 2025 7:43 PM",
    "now": "Wednesday, December 10, 2025 11:43 AM",
    "today": "Wed, Dec 10, 2025",
    "first_name": "James",
    "age": 27
  },
  "conversation_history": [
    {
      "role": "user",
      "content": "Hello!",
      "original_content": "¡Hola!"
    },
    {
      "role": "agent",
      "content": "Hello! What type of specialist would you like to make an appointment with?",
      "original_content": "¡Hola! ¿Con qué tipo de especialista te gustaría concertar una cita?"
    }
  ],
  "created_at": "2025-12-10T19:43:29.704Z"
}
FieldDescription
thread_idUnique identifier for this conversation. Use this to correlate subsequent messages.
sender_idThe visitor’s unique identifier.
languageThe detected language code (e.g., es for Spanish).
variablesAll agent variables at the time of transfer, including any request_data you passed during initialization.
conversation_historyArray of all messages exchanged before the handoff.
conversation_history[].contentThe message content (translated to English if applicable).
conversation_history[].original_contentThe original message in the user’s language. Only included when translation occurred.

​
MESSAGE

Sent for each message the user sends after the initial handoff. 
{
  "type": "MESSAGE",
  "thread_id": "0e96f65a-244b-45c9-9342-487f548195dd",
  "sender_id": "ec14ee83-fa2b-493a-b009-0e29414a1e97",
  "content": "Hello?",
  "original_content": "¿Hola?",
  "created_at": "2025-12-10T19:44:04.002Z"
}
FieldDescription
thread_idSame identifier from the initial conversation, allowing you to match messages to the correct thread.
contentThe message content (translated to English if applicable).
original_contentThe original message in the user’s language. Only included when translation occurred.

​
Post-Conversation Webhooks

Receive a webhook notification when a widget conversation ends. This is useful for logging conversations, triggering follow-up workflows, or syncing conversation data to your CRM. Post-conversation webhooks are signed using HMAC. The signature is included in the X-Webhook-Signature header. See Webhook Signing for verification details.

​
Configuration

Configure post-conversation webhooks in two ways:
  • Dashboard: Set the webhook URL in your widget settings on the platform
  • API: Pass webhook_url when creating or updating your widget
By default, a conversation times out after 24 hours of user inactivity. You can customize this via the dashboard or using config.timeoutSeconds: 
{
  "config": {
    "timeoutSeconds": 3600 // 1 hour
  }
}

​
Webhook Payload

When a conversation ends, Bland sends a POST request to your configured webhook URL with the following payload: 
{
  "widget_id": "b5f3fb6b-2285-4c73-95be-6609eca09986",
  "thread_id": "ba2cf109-4fb1-4fa5-8146-e085c9009d02",
  "visitor_id": "6eedb0cc-110f-45ed-9c05-5a66c03328f1",
  "pathway_id": "e98ef308-1380-4bea-bdfa-da54a542b12c",
  "thread_created_at": "2025-12-17T14:51:22.411Z",
  "thread_ended_at": "2025-12-17T14:51:24.655Z",
  "conversation_history": [
    {
      "id": "9b105ed8-aee3-48f1-b067-85ad5a8436c9",
      "sender_type": "ASSISTANT",
      "sender_id": null,
      "content": "Hey, thanks for calling! To get started, could you tell me your name and what kind of doctor you’d like to schedule an appointment with?",
      "original_content": null
    },
    {
      "id": "cd83215d-a7a5-4bb9-bd93-ab353f2dcb48",
      "sender_type": "USER",
      "sender_id": "6eedb0cc-110f-45ed-9c05-5a66c03328f1",
      "content": "hi what's up?",
      "original_content": null
    }
  ],
  "end_reason": "Conversation timed out after 3600 seconds of inactivity"
}
FieldDescription
widget_idThe widget’s unique identifier.
thread_idUnique identifier for this conversation thread.
visitor_idThe visitor’s unique identifier.
pathway_idThe pathway associated with this widget (if applicable).
thread_created_atISO timestamp when the conversation started.
thread_ended_atISO timestamp when the conversation ended.
live_agent_handoff_atISO timestamp when the conversation was handed off to a live agent, or null if no handoff occurred.
conversation_historyArray of all messages in the conversation. If messages have been translated after a live agent handoff, the original_content field will be populated.
end_reasonThe reason the conversation ended, which usually is either a timeout, or the pathway hit a terminal node.