Embed API Reference

Import helpers from the hosted module:

import {
  waitForThreadId,
  getThreadId,
  getDocuwormThreadId,
  getThreadIdSync,
  getDocuwormThreadIdSync,
  openWidget,
  closeWidget,
  toggleWidget,
  uploadFile,
  uploadFileFromUrl,
  uploadFileFromBlob,
  uploadFilesOnReady,
  addSources,
} from "https://cdn.docuworm.ai/docuworm.js";

Type aliases used below

type Source = {
  title: string;
  text: string;
  category?: string;
};

type UploadResult = {
  entryId: string;
  url: string;
};

type ThreadOpts = {
  element?: unknown;
  timeoutMs?: number;
};

Thread lifecycle requirement

waitForThreadId() waits for an existing thread lifecycle. Trigger thread creation first by one of these actions:

• openWidget(...)
• uploadFile(...) / uploadFilesOnReady(...)
• addSources(...)

Thread helpers

waitForThreadId(opts?)

function waitForThreadId(opts?: {
  element?: unknown;
  timeoutMs?: number;
}): Promise<string>

Returns the thread ID when available. Rejects on timeout.

Defaults:

• timeoutMs defaults to 30000.
• If element is omitted, the first docuworm-chat in document is used.

getThreadId(opts?)

function getThreadId(opts?: {
  element?: unknown;
  timeoutMs?: number;
}): Promise<string>

Alias of waitForThreadId().

getDocuwormThreadId(opts?)

function getDocuwormThreadId(opts?: {
  element?: unknown;
  timeoutMs?: number;
}): Promise<string>

Alias of getThreadId().

getThreadIdSync(opts?)

function getThreadIdSync(opts?: { element?: unknown }): string | null

Returns immediately with thread ID or null if not ready.

getDocuwormThreadIdSync(opts?)

function getDocuwormThreadIdSync(opts?: { element?: unknown }): string | null

Alias of getThreadIdSync().

Widget control helpers

openWidget(element?)

function openWidget(element?: HTMLElement): void

Opens the widget if the element is found.

No-op when no widget element is found.

closeWidget(element?)

function closeWidget(element?: HTMLElement): void

Closes the widget if the element is found.

No-op when no widget element is found.

toggleWidget(element?)

function toggleWidget(element?: HTMLElement): void

Toggles widget visibility if the element is found.

No-op when no widget element is found.

Upload helpers

uploadFile(file, element?)

function uploadFile(
  file: File,
  element?: HTMLElement,
): Promise<{ entryId: string; url: string }>

Uploads a browser File object.

Throws when the widget method is unavailable after readiness polling.

uploadFileFromUrl(url, element?, options?)

function uploadFileFromUrl(
  url: string,
  element?: HTMLElement,
  options?: { filename?: string },
): Promise<{ entryId: string; url: string }>

Important: parameter order is url, then element, then options.

Throws when URL fetch fails, CORS blocks browser fetch, or widget method readiness fails.

uploadFileFromBlob(data, options, element?)

function uploadFileFromBlob(
  data: Blob | ArrayBuffer | ArrayBufferView | string,
  options: { filename: string; mimeType?: string },
  element?: HTMLElement,
): Promise<{ entryId: string; url: string }>

Accepts Blob, ArrayBuffer, typed arrays, base64, or data URL strings.

Throws when widget method readiness fails or upload processing fails.

uploadFilesOnReady(files, element?, options?)

function uploadFilesOnReady(
  files: (File | string | Blob | ArrayBuffer | ArrayBufferView)[],
  element?: HTMLElement,
  options?: {
    timeoutMs?: number;
    filenames?: string[];
    mimeTypes?: string[];
  },
): Promise<Array<{ entryId: string; url: string }>>

Uploads mixed file inputs in parallel. Calls can be made before thread availability; widget-side queueing handles readiness.

Throws when files is empty, no widget element is found, or any individual upload fails.

Context helper

addSources(sources, element?)

function addSources(
  sources: Array<{ title: string; text: string; category?: string }>,
  element?: HTMLElement,
): void

Adds structured text sources to thread context.

No-op when no widget element is found.

Element methods

The custom element also exposes methods directly:

const widget = document.querySelector("docuworm-chat");

widget?.open?.();
widget?.close?.();
widget?.toggle?.();
widget?.getThreadIdSync?.();
await widget?.waitForThreadId?.(30000);
await widget?.uploadFile?.(file);
await widget?.uploadFileFromUrl?.("https://example.com/doc.pdf", "doc.pdf");
await widget?.uploadFileFromBlob?.(blob, { filename: "doc.txt", mimeType: "text/plain" });
widget?.addSources?.([{ title: "Summary", text: "..." }]);

Minimal orchestration example

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

const widget = document.querySelector("docuworm-chat");

widget?.open?.();

const threadId = await waitForThreadId({ element: widget, timeoutMs: 30000 });

await uploadFilesOnReady([
  "https://example.com/policy.pdf",
], widget);

addSources(
  [{ title: "Case Summary", text: "Customer requests refund." }],
  widget,
);

console.log("Ready thread:", threadId);

Error behavior

Common error surfaces:

• Waiting for thread ID before any thread trigger
• Thread wait timeout
• Widget method unavailable before registration
• URL fetch/CORS failures during URL uploads
• Upload/ingestion failures for unsupported MIME extraction paths

Use standard try/catch around async helpers.