Publish and Embed a Chat

Use a Chat Trigger to publish a conversational workflow as a Builders-hosted page, a floating widget, or an inline chat. Every accepted visitor message starts a published run. The workflow must return one final value to the trigger's Response input for Builders to display as the assistant message.

The example is a Hack It UP Event Concierge that answers questions about the agenda, registration, and venue.

Build the response loop

Connect the trigger's Out port to the processing path. Connect the final response-producing block back to Response.

The two connections have different roles:

Normalize every successful branch to one response shape. If a Condition can produce several answers, join them through a common final block before returning to the trigger.

Configure visitor-facing text

Open Chat settings and set the title, welcome message, input placeholder, thinking label, launcher label, and launcher position.

The welcome message appears before a visitor sends anything and does not create a run. The thinking label is presentation text while the workflow is executing; it does not expose internal model reasoning or block progress.

Keep promises aligned with actual capabilities. A chat that only reads an event guide should not claim it can change a booking, view personal data, or contact staff.

Read the visitor input

An accepted turn provides a chat object with message and session metadata. Downstream blocks read the visitor text as:

Copy{{input.chat.message}}

Common fields include:

Inspect a real published run before relying on optional identity fields. Never treat a public visitorId as proof of the person's account or authority.

Return one assistant message

Set Response path to the string in the output from the block connected to Response. For a final object such as:

Copy{
  "reply": "Hack It UP is hosted at New York Expo.",
  "sessionId": "<string>"
}

use:

Copy{{input.reply}}

The input here is the returning final-block output. It is not the original trigger input unless the workflow deliberately includes those fields.

Provide a safe fallback for AI, database, HTTP, integration, or timeout failures. Do not return raw stack traces, prompts, credentials, provider payloads, or internal resource IDs.

Configure appearance and preview

Choose a built-in template or Manual CSS, then open Preview.

Verify the title, welcome message, user and assistant bubbles, thinking state, composer, focus states, contrast, launcher side, and narrow-screen layout. Preview simulates appearance; it does not execute the connected workflow.

Protect access, origins, and volume

Chat supports Public, Basic, Token, and Bearer verification. Select the mode according to the actions and information available through the conversation. See Authentication for Public Workflows.

Configure Allowed origins for every site that embeds the chat. Enter one origin per line, including scheme and port where applicable:

Copyhttps://events.example.com
https://preview.events.example.com

An origin does not include a URL path. Leave the list empty when only the Builders-hosted page should use the chat. Use wildcard subdomains only when every matching host is trusted. The MDN CORS guide explains browser origin and preflight behavior.

Configure both rate ceilings:

Rate limits reduce bursts but do not verify identity, replace authorization, or guarantee a maximum total cost. Public visitor identifiers can be reset, and distributed clients can reach the global limit.

Publish and test the hosted chat

1. Connect Out and Response.
2. Configure a response path that resolves to one string on every successful branch.
3. Configure authorization, origins, client and global limits, appearance, and fallback behavior.
4. Save the draft and resolve Designer errors.
5. Preview the appearance.
6. Publish the intended version.
7. Copy and open the exact Chat URL from the trigger.
8. Send a non-sensitive message.
9. Confirm the displayed assistant response.
10. Inspect the published run, trigger input, final-block output, duration, usage, and external effects.

A later draft does not change the hosted chat until it is published.

Embed a floating widget

Open Embed and copy the generated floating snippet.

Its structure is:

Copy<script async
  src="https://builders.boilerplate.com/chat-widget.js"
  data-chat-url="<copied Builders Chat URL>"
  data-api-base="https://api.builders.boilerplate.com"
  data-mode="widget"></script>

Test the launcher on desktop and mobile. It must not cover navigation, consent controls, checkout actions, or accessibility tools.

Embed an inline chat

The inline option requires a target element placed before the script:

Copy<div id="builders-chat"></div>
<script async
  src="https://builders.boilerplate.com/chat-widget.js"
  data-chat-url="<copied Builders Chat URL>"
  data-api-base="https://api.builders.boilerplate.com"
  data-mode="inline"
  data-target="#builders-chat"></script>

Give the target a stable responsive width and height in the host layout. The MDN script element reference describes loading behavior such as async.

Protected chats should obtain visitor credentials through the trusted host application and use the generated Builders integration contract. Do not hard-code a Basic password, access token, or visitor Bearer token in public HTML, a bundled frontend file, or data-* attributes.

Verify the production host

• Add the exact production and controlled preview origins.
• Test the host Content Security Policy, CORS behavior, and browser network requests.
• Verify the widget can load without exposing credentials in page source or logs.
• Send a real message from the host, not only from Builders Preview.
• Confirm session continuity across several turns and deliberate refresh behavior.
• Test empty input, oversized input, rapid messages, timeout, downstream error, and rate rejection.
• Check that external effects are idempotent when a visitor retries after a delayed answer.

Operate the conversation safely

Validate visitor text before SQL, HTML, file paths, commands, prompts, or privileged API calls. Require verified identity again before exposing personal records or performing booking, payment, deletion, or account actions.

Keep AI tools narrower than the prompt. Enforce permissions in workflow logic and provider scopes, not in conversational instructions alone. Limit retrieved context and response size, preserve sessionId for correlation, minimize stored message content, and define retention.

Monitor message volume, per-client and global rejections, response latency, run failures, compute tokens, AI usage, and provider cost.

Troubleshoot hosted and embedded chat

Next steps

• Public Workflows
• Authentication for Public Workflows
• Chat Trigger
• Use Conversation Memory
• Run Published Workflows
• Read Block Logs and Output