htmx

The client integration supports htmx inside html blocks, enabling interactive server-driven UIs directly in the agent sidebar. Instead of static read-only data, you can build forms, toggles, and multi-step flows where each user action makes a request back to your server and swaps in fresh HTML — all without any client-side JavaScript.

How it works

When you return a block with type: "html", the ImBox client renders it inside a sandboxed iframe with htmx loaded automatically. Your HTML can use any htmx attributes (hx-get, hx-post, hx-target, hx-swap, etc.) and they will work out of the box.

The iframe runs with sandbox="allow-scripts allow-popups allow-forms" and htmx is configured in CORS mode. This means:

• Your server must handle CORS (respond with Access-Control-Allow-Origin: * and allow the necessary methods/headers)
• All URLs in htmx attributes must be absolute (e.g. https://your-server.com/endpoint) — the iframe has a null origin, so relative URLs will not resolve

HTML block fields

When returning an html block, you can include additional fields to support htmx authentication:

{
  "type": "html",
  "html": "<div hx-get='https://your-server.com/data' hx-trigger='load'>Loading...</div>",
  "id": "my-integration-instance",
  "authorization": "Basic dXNlcjpwYXNz",
  "csrf": "random-csrf-token-here"
}

Field	Type	Required	Description
html	string	Yes	The HTML content with htmx attributes. Rendered directly (not sanitized) when served from a trusted source
id	string	No	Identifies the integration instance. Sent as X-Instance-Id header on every htmx request
authorization	string	No	Sent as Authorization header on every htmx request the block makes
csrf	string	No	Sent as X-CSRF-TOKEN header on every htmx request the block makes

These headers are applied using htmx's hx-headers:inherited attribute on the wrapper element, so they automatically propagate to all htmx requests within the block — including content swapped in later.

Authorization

Use the authorization field to authenticate htmx requests back to your server. The value is sent as the Authorization header on every htmx request the block makes. For example, set it to Basic <base64_encoded_api_key> or a Bearer token to secure your endpoints.

CSRF protection

Since htmx makes POST requests from a sandboxed iframe, you should protect your endpoints with CSRF tokens:

1. Generate a secret token on your server
2. Include it as the csrf field in your html block response
3. The ImBox client will echo it back as the X-CSRF-TOKEN header on every htmx request
4. Your server validates the token on mutating endpoints

CORS

Your server must handle CORS since the iframe has a null origin. At minimum, respond with:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: *

Demo repository

A complete working example — a receipt refund flow where agents select line items and confirm refunds using htmx — is available at github.com/imbox/interactive-client-integration-demo.

It demonstrates:

• Returning html blocks with htmx attributes inside accordions
• CSRF token generation and validation
• CORS setup for the sandboxed iframe
• Server-side HTML fragment responses that htmx swaps into place
• Using hx-post, hx-target, and hx-swap for interactive checkboxes