Implementation guide

The session is identified by origin (domain) and appId, both configured with Marco in advance. The widget loads from a single script tag and starts by itself, without calling any JavaScript API.

When to use it

Landing pages, informational sites, portals with no login.

Configuration

Lives in Marco's backend, tied to your appId.

Rendering

Always a floating bubble anchored to the viewport.

Backend of your own

None needed.

Basic integration

Add these two tags to your page, one in the head and one in the body. That's all: no other call is required.

<html>
  <head>
    <script
      src="https://production.deep-talk.ai/widget/widget.js"
      defer>
    </script>
  </head>
  <body>
    <marco
      id="my-marco-widget"
      api-base-url="https://production.deep-talk.ai/widget"
      app-id="YOUR_APP_ID">
    </marco>
  </body>
</html>

Replace YOUR_APP_ID with the identifier Marco gives you. Loading the script is enough: the widget appears automatically as a floating bubble.

Lifecycle and persistence

The session is created as soon as the widget finishes loading. Each browser keeps one continuous conversation, identified by its own session_id.

Anonymous identifier

The widget generates a random session identifier the first time it loads in a browser and stores it in localStorage. It is not tied to any real identity: it only allows the conversation to resume in that same browser, and serves as a correlation identifier for events and auditing.

Resuming

Reloading the page, navigating away and back, or closing and reopening the tab or browser (same profile): in all those cases the widget finds the stored identifier and, if the session is still within its inactivity timeout, resumes the conversation and publishes SESSION_RELOADED instead of SESSION_CREATED.

Inactivity timeout

A session idle beyond its configured limit closes automatically. The next time the widget loads in that browser there is no session left to resume, and it publishes SESSION_CREATED.

Explicit close

By default the session only ends through inactivity or a user action inside the widget. If you need to close it programmatically, use MarcoWidget.finish().

Optional API: MarcoWidget

For most integrations, the section above is all you need. If your application has to react to events or close the session explicitly, the script exposes an optional global namespace, MarcoWidget, on window.

MarcoWidget.on('READY', function () {
  console.log('Marco widget ready');
});

MarcoWidget.on('SESSION_CREATED', function (msg) {
  console.log('New session:', msg.session_id);
});

// Ends the session and clears the identifier from localStorage.
// The next load starts a fresh session.
MarcoWidget.finish();

MarcoWidget.on() subscribes a callback to state events and handles origin verification for you. In this flow the session is already active by the time the script loads, so MarcoWidget is only for listening to events and, optionally, closing the session.

Events

The widget publishes session state with postMessage, emitted from its iframe to the containing window. MarcoWidget.on() is a wrapper over that same stream.

Message shape

READY, STARTED, CANCELLED and ERROR share this base shape. session_id is absent on READY and present from SESSION_CREATED or SESSION_RELOADED onwards.

{
  "source": "marco-widget",
  "version": 1,
  "type": "STATE_CHANGE",
  "state": "READY",
  "session_id": "sess_9f2a1c",
  "timestamp": "2026-08-20T14:32:04Z"
}

COMPLETED adds two fields on top of the base: created_at and finished_at.

Errors

Errors arrive as an ERROR state event, in the same shape as above, with code and message fields.

Security

Origin is this flow's primary trust signal. Every widget load is matched against the domains authorised for the given appId, and any request from an origin outside that list is rejected with unauthorized_origin. Marco also applies rate limits per appId and per IP address.

The script and its calls are served over HTTPS only, and your application must be served over HTTPS in every environment. The widget runs inside a sandboxed iframe with minimum permissions, managed automatically by the loader script.

If your application enforces a Content-Security-Policy, allow the widget domain in the three directives that govern script loading, iframe embedding and the widget's network calls.

Content-Security-Policy:
  script-src  https://production.deep-talk.ai;
  frame-src   https://production.deep-talk.ai;
  connect-src 'self' https://production.deep-talk.ai;

Your frontend starts and manages the session directly, calling MarcoWidget with a user identity signed by your backend. The browser receives the signature, never the secret.

When to use it

Your frontend already manages the user's authenticated session.

Authentication

HMAC-SHA256, verified by Marco on every call.

Rendering

Floating, or inline via component_id.

Backend of your own

For computing the signature only. No dedicated endpoint.

Loading the script

This tag loads the widget shell. The session is started separately, with the call to init. No visible interface is rendered until then.

<html lang="en">
  <head>
    <meta charset="utf-8">
    <script src="https://production.deep-talk.ai/widget/widget.js"
            defer onload="initializeMarco()"></script>
  </head>
  <body>
    <script>
      const signature = '<SIGNATURE_FROM_BACKEND>';
      const timestamp = '<TIMESTAMP_FROM_BACKEND>';

      function initializeMarco() {
        window.$MarcoWidget.init({
          apiBaseUrl: 'https://production.deep-talk.ai/widget',
          appId:      'marco-demo',
          floating:   true,
          user_id:    '323232',
          created_at: timestamp,
          signature:  signature,
        });
      }
    </script>
  </body>
</html>

Where to call init and finish

1. Load the script anywhere on your page.
2. Once the script has loaded and your user's session is available, call init(), typically in the same place where you already handle authentication: a successful-login handler, a React effect, an auth callback.
3. On context changes, call init() again with the new external_id.
4. On logout, call finish(), which closes the active session and clears the locally stored data.

Signed authentication

Your backend computes an HMAC-SHA256 signature locally using a shared secret issued by Marco, and your frontend sends it along with the user_id. Treat the secret like a server-side API key: read it from your secrets manager and never send it to the frontend, to a mobile client, or to a third party.

// Base formula
signature = HMAC-SHA256(shared_secret, user_id)

// With replay protection (recommended in production)
signature = HMAC-SHA256(shared_secret, `${user_id}:${created_at}`)

// Node.js
const crypto = require('crypto');

const signature = crypto
  .createHmac('sha256', sharedSecret)  // secret, as UTF-8
  .update(userId, 'utf8')              // user_id, as UTF-8
  .digest('hex');                      // lower-case hexadecimal

Both the secret and the user_id must be encoded as UTF-8 before signing, and the resulting signature must be represented in lower-case hexadecimal. A signature that does not follow this exact encoding fails verification even when the secret is correct.

Replay protection

By default the signature only proves that the user_id was signed by someone holding your secret, not when. Passing an optional created_at closes that gap. It is a UTC timestamp in ISO 8601 format and, when included, must be part of both the payload and the signature. Marco rejects calls whose created_at is more than five minutes away from the current time, in either direction.

Parameters

Metadata example

{
  "specialty": "oncology",
  "diagnosis": "HER2-positive breast cancer, stage III",
  "current_treatment": "trastuzumab + pertuzumab, cycle 4 of 6",
  "disease_state": "partial response, stable since last imaging",
  "ecog_status": "1",
  "line_of_therapy": "second line"
}

Prefer descriptive, self-explanatory keys over abbreviations. metadata is interpreted by the agent when the session starts, so clarity here translates directly into better answers. The example is illustrative: longer text or summaries also work if that represents your data better.

Lifecycle and persistence

Two independent lifetimes apply: the signature's validity window and the session itself.

Signature window

When created_at is included, the signature is valid for five minutes from issue. It is recomputed, or reused within its window, on every call to init or finish.

Session

Runs for an independently configured lifetime once started. It extends with activity and ends through an explicit close, inactivity, or expiry of that lifetime.

Switching context

To point the widget at a different patient or record, call init() with the new external_id. This does not update the open session: it is a distinct session, new or resumed if that context already had an active one.

Reloading, navigating and closing the tab

All three behave the same way: the iframe is discarded, but the identifier persists in localStorage. The next call to init() with the same user_id and external_id attempts to resume automatically, as an effect of that same call.

Explicit close

MarcoWidget.finish() closes the session immediately and clears the stored identifier. After finish(), a call to init() with the same pair starts a fresh session.

Events

The widget publishes state with postMessage from its iframe to the containing window. The loader script also exposes MarcoWidget.on(event, callback), a wrapper over that same stream that handles origin verification for you.

MarcoWidget.on('READY', function () {
  console.log('Marco widget ready to receive init()');
});

MarcoWidget.on('SESSION_CREATED', function (msg) {
  console.log('New session:', msg.session_id);
});

MarcoWidget.on('ERROR', function (err) {
  console.error('Marco widget error:', err.code, err.message);
});

Message shape

session_id and external_id are absent on READY and present from SESSION_CREATED or SESSION_RELOADED onwards.

{
  "source": "marco-widget",
  "version": 1,
  "type": "STATE_CHANGE",
  "state": "SESSION_RELOADED",
  "session_id": "sess_9f2a1c",
  "external_id": "patient_789",
  "timestamp": "2026-08-20T14:32:04Z"
}

Errors

The signature is computed locally on your backend, with no round trip to Marco. An invalid or expired signature is discovered when the widget tries to use it, and arrives as an ERROR state event.

Security

The user_id is never trusted on its own. Marco recomputes the signature independently and compares it before starting or continuing any session. Every call to init or finish is also matched against the domains authorised for your account, and rejected with unauthorized_origin if the origin is not on the list, even when the signature is valid.

Application-level authorisation

A valid signature confirms that your backend, holding the secret, signed that user_id. Checking whether that user should have access to the record described in metadata is your own application's responsibility, before calling init(). The access decision is made at that moment; the signature only carries it.

Content-Security-Policy

Content-Security-Policy:
  script-src  https://production.deep-talk.ai;   // bootstrap script
  frame-src   https://production.deep-talk.ai;   // sandboxed iframe
  connect-src 'self' https://production.deep-talk.ai;  // widget calls

The script and its calls are served over HTTPS only. The widget runs in a sandboxed iframe with minimum permissions, and uses localStorage for resuming; that cache is cleared when you call finish().

Your backend creates the session directly with Marco's backend. Your frontend never receives any session-scoped data, only an opaque, single-use, short-lived token to start the chat.

When to use it

When the clinical context must stay on the server at all times.

Authentication

Bearer client_secret, server to server.

Rendering

An <iframe> you control.

Guarantee

Architectural: the browser holds nothing it could use to build or read that data.

Creating the session

Your backend calls Marco's session endpoint over HTTPS. The credential is presented as a bearer token and is long-lived: it is issued once per client, not per session.

POST /launch_token
Host: production.deep-talk.ai
Authorization: Bearer <client_secret>
Content-Type: application/json

{
  "app_id": "oncology-widget",
  "user_id": "doctor_123",
  "metadata": {
    "specialty": "oncology",
    "diagnosis": "HER2-positive breast cancer, stage III",
    "current_treatment": "trastuzumab + pertuzumab, cycle 4 of 6"
  }
}

Response

{
  "launch_token": "lt_7Kx0mQe2vB…",
  "session_id": "sess_9f2a1c",
  "expires_at": "2026-08-20T14:37:00Z"
}

launch_token is opaque, single-use and short-lived, and carries none of the session's underlying data. Keep session_id to correlate with your own audit records; you will not need it again to interact with the widget.

Embedding the iframe

Your frontend renders an iframe pointed at the session URL with the launch_token attached. The token in the URL is the only input this flow requires from your frontend. URL-encode the value, since it may contain characters that need percent-encoding.

<iframe
  src="https://production.deep-talk.ai/chat?launch_token=lt_7Kx0mQe2vB%2E…"
  sandbox="allow-scripts allow-same-origin allow-forms"
  allow="clipboard-write"
  referrerpolicy="no-referrer"
></iframe>

Validation

When the iframe loads, Marco validates the token before showing any content.

1. Lookup. Marco looks up the launch_token against the created session.
2. Validation. It checks that the token exists, has not expired, has not been used, and that the request origin matches the domains authorised for your account.
3. Single-use consumption. If valid, the token is marked used immediately and cannot be used again.
4. Start. Marco returns the minimum needed to render the widget: session_id, ready state and display configuration, derived from the metadata already consumed on the server.
5. Ready. The widget becomes interactive and publishes READY to the container.

Note also that READY only means the widget is interactive: the session's metadata is processed only when the user takes an explicit action to begin.

Lifecycle and expiry

Two independent lifetimes apply. The launch_token lasts five minutes and is single-use: it exists solely to move the iframe from "holds a reference" to "running session". The session runs for a longer, per-integration lifetime, extends with activity, and ends through an explicit close, inactivity, or expiry.

Closing the tab, reloading the page or unmounting the iframe on navigation all produce the same result: the iframe is discarded and the session ends with it. The token was already consumed the moment the previous load succeeded, so it cannot be reused. Your frontend must request a new session from your backend, which issues a new token with the updated context. If instead your container keeps the iframe mounted across navigation, the session stays active until its inactivity timeout or an explicit close.

Switching context

metadata is fixed when the session is created and cannot be updated on a running session. To point the widget at a different patient or record, request a new session with the new context.

Events

The widget publishes state directly to the containing window with postMessage. Your page listens with a standard listener. Always check event.origin before reading event.data, never compare it against '*', and never trust a message that does not include source: 'marco-widget'.

const MARCO_ORIGIN = 'https://production.deep-talk.ai';

window.addEventListener('message', (event) => {
  if (event.origin !== MARCO_ORIGIN) return;
  const msg = event.data;
  if (msg?.source !== 'marco-widget') return;

  switch (msg.state) {
    case 'READY':     /* the widget is interactive */     break;
    case 'STARTED':   /* the user sent a query */         break;
    case 'COMPLETED': /* session finished */              break;
    case 'CANCELLED': /* cancelled by user or app */      break;
    case 'ERROR':     /* see the errors section */        break;
  }
});

Sending commands to the widget

Your container can send commands the same way, targeting the iframe's contentWindow. Always pass the exact target origin as the second argument, never '*', so the browser refuses to deliver the message if the iframe has navigated somewhere unexpected.

const iframeWindow = document.querySelector('iframe').contentWindow;

iframeWindow.postMessage({
  source: 'marco-host',
  version: 1,
  type: 'COMMAND',
  action: 'CLOSE',          // the only action currently supported
  session_id: 'sess_9f2a1c'
}, MARCO_ORIGIN);

On receipt, the widget checks the origin against those authorised for your account before executing. A command from an unregistered origin is discarded silently: the widget neither acts nor emits ERROR, since an unrecognised origin may not be a legitimate sender. A valid CLOSE ends the session immediately and the widget emits CANCELLED back, so your container gets a clean, correlatable confirmation.

The COMPLETED payload

{
  "source": "marco-widget",
  "version": 1,
  "type": "STATE_CHANGE",
  "state": "COMPLETED",
  "session_id": "sess_9f2a1c",
  "created_at": "2026-08-20T14:32:00Z",
  "finished_at": "2026-08-20T14:36:12Z",
  "metadata": {
    "query_summary": "Asked about second-line options for HER2-positive…",
    "final_synthesis": "Reviewed second-line options for HER2-positive…"
  }
}

Errors

Errors happen at two moments and surface differently in each. At session creation they are standard HTTP responses to your server-to-server call.

From iframe validation onwards, errors arrive as an ERROR state event with code and message fields.

Security

Both session creation and iframe embedding happen over HTTPS only. Mixed content is rejected by the browser before Marco is involved. Every token validation matches the requesting origin against the domains authorised for your account, and rejects with unauthorized_origin even when the token is valid.

Application-level authorisation

A valid launch_token only confirms that your backend's client_secret was presented correctly. It does not guarantee that the given user_id should have access to the record described in metadata: that check is solely your application's responsibility, at the moment your backend calls the endpoint. Once the token is created, the access decision has already been made; the token only carries it.

Content-Security-Policy

In this flow your page never calls Marco directly: only your backend and the iframe itself do. So your container page's CSP only needs to allow Marco's origin in frame-src.

Content-Security-Policy:
  frame-src https://production.deep-talk.ai;

No cookies

The iframe holds its session credential in memory after start-up and attaches it explicitly to every subsequent call, avoiding third-party cookie restrictions.