How to add a chatbot to WordPress with block, widget or shortcode
A detailed post-installation guide for choosing the right placement, configuring page-specific assistants and testing the complete visitor experience.
To add a chatbot to WordPress reliably, connect one default assistant, choose the right placement and test the complete public visitor experience.
This guide starts after the WebChatAgent WordPress plugin is active. It explains exactly how to connect the default assistant, choose between a site-wide floating widget and an inline chat, and place the chat with either the native Gutenberg block or a shortcode.
The controlled example uses WordPress 7.0.2, WebChatAgent plugin 1.1.4, an English Light Mode assistant and two fictional pages on Northstar Support Demo. Every placement is loaded on the real WordPress front end; the final chat answer is retrieved from an indexed test source.
Use one default Chatbot ID when the same assistant serves the whole site. Add a per-block or per-shortcode ID only when a page intentionally needs another assistant, and document that exception so editors do not accidentally show two different bots.
Privacy-protected two-click player
How to Add a Chatbot to WordPress (Block, Widget & Shortcode)
Add a chatbot to WordPress with the WebChatAgent plugin: connect the assistant, choose a widget, Gutenberg block or shortcode and verify a real answer.
The YouTube player stays blocked until you choose Play. Loading it connects your browser to YouTube and may transfer technical data to Google.
Open directly on YouTubeWhat you will have at the end
- A default assistant connected to WordPress
- A clear decision between floating and inline placement
- A published Gutenberg inline-chat page
- A reusable shortcode for page builders and widgets
- A documented per-page Chatbot ID override
- No accidental duplicate chat placement
- A verified source-backed visitor answer
Before you start
- The official WebChatAgent WordPress plugin is installed and active
- A WebChatAgent assistant with one completed knowledge source
- The exact WordPress hostname is listed under Allowed websites
- WordPress administrator or editor access
- A staging or disposable page for the first publish test
- Permission to clear optimization and CDN caches
One assistant, three placement choices
General settings store the default Chatbot ID. The floating switch adds a button site-wide; the Gutenberg block and shortcode render an inline chat only where editors place them.
The inline methods work independently from the floating switch. That flexibility is useful, but it also means one page can show both placements unless you choose deliberately.
01–08
Set it up step by step
Connect the default assistant and understand what WordPress stores
The plugin stores the Chatbot ID and floating-widget switch; assistant design and answers stay in WebChatAgent.
Open WordPress Admin → WebChatAgent → General. Paste the complete UUID into Chatbot ID, enable the widget only if you want a site-wide floating button and select Save Settings. The read-only title and preview should update to the intended assistant.
The blue information panel is important: appearance, position, messages, knowledge and answer behavior are managed in the WebChatAgent dashboard. WordPress should not become a second, conflicting source of configuration.
A successful save proves local storage. A loaded assistant title and preview additionally prove that the ID, public configuration request and Allowed websites entry agree.
Choose floating widget, Gutenberg block or shortcode
Match the placement to the visitor task instead of enabling every option.
Use the floating widget for site-wide support that should remain available while visitors move between pages. Use an inline chat when the conversation belongs inside one support, pricing, onboarding or knowledge page.
Open Inline Embed to see the two editor methods. Gutenberg users should prefer WebChatAgent Inline Chat because editors can discover it visually and set an optional page-specific ID. Classic Editor, Elementor, Divi and text-widget users can paste `[webchatagent_inline]` into a shortcode-capable element.
Both inline methods reuse the General Chatbot ID by default. This keeps later assistant changes centralized and reduces maintenance.
Preview the site-wide floating widget on a real page
Check the public page, not only the plugin preview.
Open a normal front-end page and confirm the chat button stays inside the lower-right safe area without covering cookie controls, checkout actions or mobile navigation. Open it once and check the assistant title, welcome copy, colors and keyboard focus.
The floating widget loads wherever the active theme calls `wp_footer()`. If it appears in the admin preview but not on the site, inspect the theme footer and optimization plugin before changing the Chatbot ID.
Test the homepage, one cached inner page and a private browser session. A warm administrator session can hide consent, cache and persistence problems.
Add the native WebChatAgent block in Gutenberg
Search for “chat”, select the branded block and place it after useful context.
Create or edit the target page, open Block Inserter and search for “chat”. Select WebChatAgent Inline Chat under Embeds. Add a clear heading and one sentence that tells visitors what they can ask before the block.
The editor shows a placeholder instead of loading the live remote widget. That is intentional: it avoids starting visitor sessions or consuming chat traffic while an editor rearranges content.
Publish first on staging. Open the public URL and verify the full chat height on desktop and mobile; do not judge the final layout only from the editor placeholder.
Use a page-specific Chatbot ID only when needed
An override can make the inline chat differ from the floating assistant.
Leave Chatbot ID empty in the block sidebar to inherit General settings. Enter a complete UUID only when this page intentionally needs a specialist assistant—for example, onboarding help inside the onboarding portal while the floating bot remains general support.
Record the page URL, assistant name and override owner in your content documentation. When an assistant is deleted or replaced, hidden overrides are otherwise easy to miss.
If inline and floating chats answer differently, compare their public assistant names and IDs before debugging knowledge or model settings.
Embed the chatbot with a shortcode in page builders
Use the default shortcode first; add an ID attribute only for a documented exception.
Add a Shortcode or HTML-capable module and paste `[webchatagent_inline]`. This is the safest choice for Classic Editor, Elementor, Divi, reusable widgets and templates that execute WordPress shortcodes.
For a deliberate specialist assistant use `[webchatagent_inline chatbot-id="UUID"]`. The alias `chatbot_id="UUID"` exists for builders that strip hyphens from attribute names.
Do not paste the raw JavaScript installation snippet into the same page when the plugin is active. The plugin already loads the inline asset only where the block or shortcode is rendered.
Avoid duplicate chats and align consent and cache rules
The floating switch is independent from every inline placement.
If an inline page should contain only one chat, disable the global floating switch for the whole site or remove the inline block from that page. Because the plugin has no per-page floating exclusion, mixed strategies should be planned before rollout.
Load optional chat or tracking storage only after the consent state required by your policy. The WebChatAgent widget accepts consent state, but your WordPress consent manager still decides when optional scripts may run. Document the legal basis, retention and processor information for your deployment.
Exclude `web-chat-agent.js` and `chat-widget-inline.js` from delay, script combination and aggressive minification. Purge WordPress, page-builder, reverse-proxy and CDN caches after changing placement or ID.
Verify one grounded answer on the public WordPress page
A visible widget is only the beginning of the acceptance test.
Open the published page in a fresh visitor session. Confirm one inline widget, the intended floating state, English controls, readable mobile width and no horizontal overflow. Then ask a question whose exact answer exists in an indexed source.
Verified input: “What is the exact onboarding code for the WordPress embed lab?” Expected and observed result: `WP-EMBED-47`. The real inline widget answered, “The exact onboarding code for the WordPress embed lab is WP-EMBED-47.”
Repeat the same question after plugin, theme, cache, consent, assistant or knowledge changes. Also test one unsupported question and require an honest no-information response rather than a plausible guess.
Example & result
See the practical test and its result
Every tutorial includes a fixed input, the expected outcome and a transparent record of what was actually verified locally.
Practical example: How to add a chatbot to WordPress with a widget, Gutenberg block or shortcode
This exact scenario was completed with the temporary tutorial account.
Exact test input
Open the published Northstar Support WordPress page and ask: “What is the exact onboarding code for the WordPress embed lab?”
Expected result
The inline widget loads in English and returns the exact value WP-EMBED-47 from the indexed test source.
What was actually verified
The disposable WordPress page rendered the real WebChatAgent inline component and answered: “The exact onboarding code for the WordPress embed lab is WP-EMBED-47.”
Tips & tricks
Make the setup reliable
Test with realistic examples, record your baseline and change one setting at a time. That makes real improvements visible.
Keep one default assistant
Most sites need one default ID. Use overrides only for clear specialist journeys and review them during every assistant migration.
Design inline chat as page content
Introduce what visitors can ask, provide enough height and place fallback contact options nearby. A blank chat box without context is less persuasive.
Retest the public URL after every cache change
Optimization plugins can delay or combine the two widget assets. Verify in a fresh private session after every performance-rule change.
When something does not work
Troubleshooting
Check status, permissions and test data systematically before changing the model or prompt.
Settings save, but the assistant title does not load
Compare the complete UUID and exact Allowed websites hostname. Production, `www` and staging hosts are separate entries. Save WebChatAgent first, reload WordPress and inspect the displayed title before continuing.
The Gutenberg block is visible in the editor but empty on the page
Confirm a default or per-block Chatbot ID, purge every cache and exclude the inline widget asset from script delay. Then inspect the public page for `web-chat-agent-inline` and browser errors.
Two chat interfaces appear on one page
The floating switch and inline placement are both active. Decide whether this page needs global access, embedded context or both; then disable one placement and clear caches.
The shortcode is printed as text
Use a WordPress Shortcode block or a page-builder element that executes shortcodes. Plain code, paragraph and escaped HTML modules display the characters without running the handler.
The widget language is wrong
Set the chatbot language-detection source to HTML lang and make sure the WordPress page declares the intended locale. Clear cached widget files and retest in a new session.
Ready for a production-style test
Publish the chosen placement on staging, run the known-answer and honest-unknown tests on desktop and mobile, document every per-page ID override and only then repeat the rollout on production.