Integrate Live Chat identity and messaging

Use a Chat App's public ID to embed Protodesk Live Chat on an allowed website. The public ID identifies the widget; it is not a credential. Chat sessions, identity tokens, and server secrets are separate. This guide describes the current website widget and the scoped Chat API; test the full visitor-to-agent-to-visitor path in your own workspace before relying on it for customer support.

Install the website widget

In Settings → Live Chat, create or select a live Chat App, enable it, and add each allowed website as an exact HTTPS origin. Copy the Installation code shown there and place it before your site's closing </body> tag. The code loads https://chat.protodesk.io/widget.js with your public Chat App ID. Paths and wildcard origins are not accepted as allowed websites.

The widget runs its conversation UI in an isolated Protodesk-origin iframe. Let the installer manage its origin-bound bootstrap and session exchange. Do not put a Chat server secret, Platform API key, refresh token, or identity token in the script tag, URL, page source, or analytics. The public ID alone cannot read a customer's messages.

Once the script has loaded, window.Protodesk exposes open(), close(), toggle(), and on("ready" | "open" | "close" | "unread" | "error", handler). Keep the widget's own iframe and message protocol intact rather than trying to recreate its private handshake from page JavaScript.

Choose anonymous or verified identity

When Anonymous visitors is enabled, the widget can create an anonymous Chat session. Its installation ID is only a lookup value; the resume secret is the proof needed to return to the same anonymous identity. The widget manages these values. Clearing browser storage or losing the resume proof can produce a new identity; do not promise that anonymous history follows a person across browsers or devices.

For signed-in visitors, a trusted server can mint a single-use Chat identity token from a server-held secret scoped to one Chat App. Use a stable, opaque externalUserId from your account system, not an email address as the identifier. The server secret may mint identity tokens but does not grant conversation-read access. It must never be sent to the browser. Server-secret provisioning is not currently exposed as a self-service control on the Live Chat settings page; arrange access through a supported administrator workflow before implementing verified identity.

After your own authenticated endpoint returns a fresh identity token, give the widget a provider function:

await window.Protodesk.identify(async () => {
  const response = await fetch('/your-server/chat-identity-token', {
    credentials: 'include',
    cache: 'no-store',
  });
  if (!response.ok) throw new Error('Unable to verify chat identity');
  const { identityToken } = await response.json();
  return identityToken;
});

/your-server/chat-identity-token is your own authenticated endpoint, not a Protodesk route. It should authenticate the current site user, mint a token on the server through POST /v1/chat/identity-tokens, and return only the short-lived token to that user's browser. Do not cache or log it. The provider may be called again when the widget needs a fresh session, so mint a new token rather than reusing an already consumed one.

Call window.Protodesk.logout() when the site user signs out or switches accounts, and wait for it to complete before showing chat for someone else. identify() and continueAnonymously() also replace the current widget identity. An anonymous-to-verified history merge is an explicit, separate operation; identifying a user does not automatically prove or merge their anonymous conversation history.

Understand Chat API scope

The customer Chat API lives under /v1/chat, not the workspace Platform API's /v1/conversations routes. A short-lived Chat access token is scoped by the server to one workspace, Chat App, and customer. Client-supplied conversation IDs are only lookup keys; they do not grant access to another customer. Browser API calls are made by the isolated https://chat.protodesk.io iframe and remain bound to the website origin allowed when the session was created. A native client omits the browser Origin header; it must still use the appropriate Chat session flow.

With a valid Chat session, clients can read the authenticated bootstrap and that customer's Chat-owned conversations, create a conversation, list its public messages, and send a visitor message. The Chat send route requires both an Idempotency-Key and a stable clientMessageId for retry reconciliation. Keep the exact request content on retries. The message list excludes internal notes; it returns a newest page whose messages are chronological within that page, and its nextCursor loads older history. Mark-read advances through a public message boundary, while typing is an ephemeral best-effort signal, not a stored message.

When the deployed Chat App advertises attachment support, first initiate an upload, transfer bytes using the returned short-lived method-specific URL and required headers, complete validation, and wait until the attachment is ready before including its ID in a message. Treat upload and download URLs as temporary bearer capabilities; do not log or persist them. Use the authenticated download operation to obtain a scoped download URL.

Realtime uses a one-time ticket and a resumable WebSocket, not the Platform API's workspace SSE stream. Keep the ticket and cursors out of logs, reconnect from the last handled event, and resync the scoped conversation if replay is no longer available. The website widget manages this flow; direct clients need to implement the protocol rather than borrowing a workspace event token.

Check capabilities and delivery before rollout

Read the Chat App's public configuration or authenticated bootstrap to see what the deployed app actually advertises. Do not infer that every route in a design contract is enabled. In the current server, push-target registration routes are not mounted, and the public capability response does not advertise push registration; do not build a push-notification setup around them yet. SDK contract sketches are not evidence of a released mobile SDK.

A successful visitor message response records the customer's Chat message. It does not by itself establish that an agent can reply or that an external notification reached someone. The current shared dashboard composer rejects external Live Chat sends, so do not promise agent replies through that UI. Test anonymous and verified entry, identity switching, inbound message visibility, a supported agent-reply path, receipt in the widget, attachments if needed, reconnect, and origin rejection with your own test identities. Do not expose the integration to customers until your actual end-to-end support path passes.