Connect the Chat Widget to Your Desk

Install the hosted ResponseCX widget, find its conversation in Chat Desk, and verify human takeover, replies, and internal notes.

Outcome: a visitor sends a message on your website, your team finds the same conversation in Chat Desk, and an operator reply appears in the widget.

This guide uses the hosted Widget Builder v2 loader in response-one-prod. The standalone widget integration has a different mounting API and configurable backend endpoints. Mounting that standalone component does not by itself connect its backend to ResponseCX Chat Desk.

1. Configure your hosted widget

Open Widget Builder in the intended organization. Select the support agent, configure the greeting and appearance, and add your allowed website origins. The builder requires valid exact origins, such as https://shop.example.com; confirm the actual scheme and host used by your test page.

Save the widget and use the builder’s publication controls when you are ready for customer traffic. A saved inactive widget is not a live deployment. An agent preview alone does not test the permanent widget ID, origin checks, or installed loader.

2. Install the generated snippet

Prefer the snippet generated for your widget. Its basic form is:

<script
  src="https://response.stateset.com/widget/v2/loader.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-api="https://response.stateset.com"
  async>
</script>

Replace YOUR_WIDGET_ID with the permanent widget ID from the builder and place the script before the closing body tag. The hosted loader initializes the widget; this path does not require the separate React/UMD mounting example. Do not put a private service API key in the script. If your site uses a content security policy, allow the loader origin in script-src and the API origin in connect-src.

Test the actual published page on an allowed origin. If using a tag manager or cached site, confirm the snippet reached the live page and was not inserted twice.

3. Follow a message into the desk

VISITORHosted widget

Sends a message with its session and thread context.

RESPONSECXAgent and transcript

Handles the message and persists the conversation for the organization.

OPERATORChat Desk

Reads the thread and saves a reply for the same visitor conversation.

Send a unique test message, such as “Widget handoff test: shipping policy.” In the desk’s Chat view, find that text and compare the thread identity and agent. The widget runtime persists chat threads and messages and also records response evidence. The desk combines native chat threads with eligible response-backed records; a response row alone is not proof that an editable native thread exists.

The visitor’s open widget receives thread updates through streaming with polling fallback. An operator reply must be saved to the same thread and retrieved by that visitor session to appear. Desk event updates and widget updates are separate connections.

4. Verify a human handoff

1. In Chat Desk, Claim the test conversation and choose Pause AI / take over.
2. Send another message from the same visitor widget. When the widget backend detects human takeover, it saves the customer’s message and returns a handoff acknowledgement instead of generating a new AI answer.
3. Use Send reply in the desk. Confirm the result says the transcript was saved, then watch the reply appear in the visitor widget.
4. Add a clearly marked test internal note in the desk. Confirm the team can see it and the visitor cannot. Public widget transcript reads filter internal-note messages.
5. If returning the conversation to automation, clear the relevant takeover state and verify the next test message. Releasing assignment alone does not clear every takeover signal.

Takeover is checked before generation using thread and latest-response state. The current public chat handler continues with AI if that state lookup fails. Treat the desk pause as conversation coordination, not a fail-closed emergency stop for the whole deployment.

Completion checklist

• The installed widget uses the intended widget ID, agent, organization, and allowed origin.
• A real visitor message is visible in the desk under the matching conversation.
• Human takeover is observed on a subsequent visitor message.
• An operator reply appears in that same visitor session.
• An internal note remains absent from the public transcript.

Keep the thread ID and the observed results in your onboarding record.

Troubleshooting

Symptom	Check
Builder preview works, website does not	Widget publication, exact allowed origin, installed script, permanent widget ID, and browser network errors
AI responds but desk lacks messages	Transcript persistence and organization/thread mapping; inspect server errors rather than assuming every AI response was stored
Reply saved but visitor sees nothing	Same thread/session, open widget, blocked streaming/polling, and reply versus note audience
AI responds during a handoff	Actual takeover state and backend lookup failures; assignment alone is not enough
History or updates are rejected	Origin/session/thread authorization; keep the loader’s returned thread context intact

Continue with desk operations or channel coverage.

Implementation checked against response-one-prod on 2026-09-20: pages/widget-builder.js, public/widget/v2/loader.js, pages/api/public/widget/chat.js, public widget v2 thread routes, lib/widget/publicChatThreads.ts, and lib/chat-desk/thread-state.ts.