Overview
Install the supplied embedded text-chat widget in a Django base template. Django renders the page on the server; a browser module mounts the panel after its custom element is connected. This recipe installs an embedded panel for public support using an existing Voiceflow agent.
Building your own interface? Framework-specific custom chat and voice guides are planned. Use Chat agents and Voice agents for their separate API contracts.
Before you begin
Prepare the published public agent and framework access.
Obtain the project ID, alias and expected answer from the agent owner before editing the files. This starter uses the public verify.projectID contract; client-key, private/prototype and Private Cloud configurations require their own compatible installation. Keep framework application secrets, website login tokens and personal/service API keys on the server. See Django static files for the platform behavior.
Install the widget
Configure and activate one browser-owned chat panel.
Download the complete starter
Download the Django starter and extract it. It includes the entry files, dependency locks and static/widget/widget.js, widget-config.js and widget.d.ts. The helper loads the supplied widget from its CDN; no Voiceflow npm package is needed.
For an existing site, copy only the widget integration and merge the placement below into your existing layout. Keep its other configuration. Remove any earlier Voiceflow snippet: this global widget API supports one active widget per document.
Choose the public project and Published release
Edit static/widget/widget-config.js:
Replace both YOUR_ values with the supplied project ID and Environment alias. environmentID and versionVariant: 'published' select that Environment’s Published release; legacy versionID compatibility is separate. Raw HTML is disabled while ordinary Markdown remains available.
Add the browser integration
Copy the widget folder into a configured static-files directory and include the element/module once in your shared base template. Use Django’s {% static %} tag to generate the script URL. The starter includes django.contrib.staticfiles, STATICFILES_DIRS, STATIC_URL and a separate STATIC_ROOT for collection.
static/widget/widget-element.js:
templates/base.html:
Run the local installation
Create an environment, install the locked dependencies and start Django’s local server:
Open http://localhost:5173. One embedded chat panel should replace the loading message. The installed panel proves browser startup; complete the visitor test to verify answers from your actual agent.
Handle widget lifetime and identity
Keep navigation, removal and guest conversations predictable.
The example uses normal document navigation rather than a client router. Each new page creates its own widget. The custom element disposes the previous UI on removal/pagehide and handles browser-cache restoration. Its files are safe to serve as static JavaScript; they contain no Django session secret or server API credential.
The helper serializes load() and disposal, reuses its own downloaded loader, and creates a fresh inner HTMLElement for each mount. It calls destroy() only for the widget it owns, then removes that target. Keep the outer container’s children under widget ownership.
Browser userID, page context and launch values do not authenticate a customer. This public widget supplies no private-record authorization. Protected operations require a trusted backend boundary on every read/write, turn and resume; use the canonical trusted-customer guidance before adding them. Widget destroy() does not delete transcripts or undo an in-flight business action.
Use partial-page navigation
Keep the support element outside the region your partial-page library replaces when the conversation should survive. If a replacement removes the element, its cleanup runs and the next connection starts fresh. Libraries that preserve the element while rewriting its children need an explicit exclusion for this widget-owned subtree; the starter does not configure HTMX or another router.
Test a visitor conversation
Verify the installed widget, replies and framework navigation.
Use a staging deployment with the final project/release configuration. If approved-domain restrictions are enabled, have the agent owner allow that origin. Check that the site’s content security policy permits the widget’s script, styles, fonts and runtime connections.
Open as a visitor
Open a fresh browser session at the staging URL. Accept any configured notice. Confirm one panel appears and that input, scrolling and keyboard behavior work at desktop and phone widths.
Check a question and follow-up
Send the prepared support question and a related follow-up. Both replies must match the intended agent/release and preserve the expected conversation context. Locate this exchange in the intended project’s Transcripts.
Navigate and return
Use the starter’s About link and Back. Compare the result with widget lifetime: a removed owner should clean up, then the next mount should show a fresh conversation. Open the nested route directly too. Check that navigation never leaves two active panels or a blank cached copy.
Check slow startup and recovery
Leave while the CDN/setup is pending, then return. There must be no overlapping load or detached-target error. Interrupt and restore the network. If a business action’s result is uncertain, check its outcome before retrying. Reload to confirm the fresh-start policy. If the site has sign-in, remove the widget during logout/account change and confirm that old messages do not return for another account.
The panel stays blank
Trace the browser entry and configuration before changing the agent.
Confirm both placeholders were replaced and that the documented module/component actually executes in the browser. Check missing static files, blocked CDN/style/font/runtime requests, project public access, the Environment alias, its Published release and approved origins. The helper gives the target a visible height. After repairing a failed or partial load, reload the document; it does not automatically retry the SDK.
Navigation duplicates or restarts support
Remove other snippets and keep one owner. Compare your installation with the local lifecycle instructions, including any framework cache or DOM-replacement behavior. A real unmount intentionally starts fresh with memory persistence. Preserve the helper’s cleanup rather than calling load() after every route event.
The wrong agent answers
Check the published route with a fresh conversation.
Compare the installed project ID and Environment alias with the agent owner’s values. Confirm the known answer exists in that Published release; editing Draft does not change it. Use Environment publishing before retesting.
Release and maintain the installation
Publish the agent and website independently, then test production.
Publish the agent and deploy the application
Have the agent owner publish the reviewed Environment, including widget-setting changes. Set DJANGO_DEBUG=0, a persistent server-only DJANGO_SECRET_KEY, and the correct DJANGO_ALLOWED_HOSTS. Run python manage.py collectstatic --noinput, then serve STATIC_ROOT through the production web server and the app through its normal WSGI/ASGI server. Django’s development runserver is the local fixture, not the production static-file service.
Accept the production route
Open the actual HTTPS production URL and repeat the visitor test, including a direct nested-route request. Agent publication and site deployment are separate releases. Record the application commit, Environment release and observed widget version.
Update, roll back or remove
Change the responsible release and repeat the visitor test.
Keep the last working application build and public widget configuration. The CDN URL moves independently of the framework lockfile, so test after widget updates. App rollback does not roll back the agent or delete transcripts. To remove support, remove its entry/component and deploy, retaining cleanup during removal. After any change, use the same visitor test.
Custom interface guides
Planned framework guides for your own chat or voice UI.
Custom-interface walkthroughs for Django are planned, separate from the completed supplied-widget procedure.