Thread Routing

A Docuworm thread stores conversation history and attached context. In production, route threads with a stable external reference.

Use `thread-ref` as your routing key

<docuworm-chat
  access-token="worm_xxx_your_token"
  thread-ref="case_12345"
></docuworm-chat>

Docuworm creates or reuses the same conversation for the same thread-ref + organization context.

Recommended key patterns

case_<id>
ticket_<id>
order_<id>
account_<id>

Use prefixes to avoid collisions across entity types.

When a thread is created

In widget runtime, thread creation is triggered when the chat is used (for example: opening the widget, adding sources, or uploading files).

Use helpers to synchronize safely:

import {
  openWidget,
  waitForThreadId,
} from "https://cdn.docuworm.ai/docuworm.js";

const widget = document.querySelector("docuworm-chat");
openWidget(widget);
const threadId = await waitForThreadId({ element: widget, timeoutMs: 30000 });

Sync thread ID to your backend

await fetch("/api/cases/12345/docuworm-thread", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ threadId }),
});

Store this linkage in your system for traceability and analytics.

If you omit `thread-ref`

If no thread-ref is provided, the widget uses a fresh conversation lifecycle instead of deterministic routing. For production entity workflows, always provide thread-ref.

Framework notes

Across React, Vue, and Svelte, the routing rule is identical:

Render <docuworm-chat> with a stable thread-ref.
Hold an element reference.
Trigger thread creation, then call waitForThreadId() and sync to your backend.