How to Set Up the Vapi Web Widget on WordPress
This guide walks through installing the Vapi web widget on a WordPress site. By the end, visitors can click a floating button and start a live voice conversation with your Vapi assistant without leaving the page. No coding is required beyond copy and paste.
What you need before installing the widget
Three things must be in place before you touch your WordPress site. Each is required for the widget to load and connect calls correctly.
-
A Vapi account with a Public API Key
Log in to your Vapi dashboard and copy your Public API Key. Unlike private keys, public keys are safe to expose in your website code. Never use the private key in client-side widget code.
-
An Assistant ID from a configured Vapi assistant
Navigate to Assistants in the left sidebar of the Vapi dashboard and copy the ID of the assistant you want to embed. The widget will connect calls to this specific assistant.
-
WordPress admin access with script permissions
You need permission to add scripts to your WordPress site. On most configurations, this is available to Administrator role users. If your site restricts header and footer script injection, you will need a plugin or theme-level injection point.
Choose your WordPress install method
Three methods work for injecting the Vapi widget script into a WordPress site. Choose the one that matches your setup and access level.
Code Snippet Plugin
Install a free plugin such as Code Snippets or WPCode. Paste the widget script into a new snippet set to run in the site footer. This is the cleanest method because the script is not tied to your theme.
Theme Footer Injection
If your theme provides a footer script injection area in its settings, paste the widget script there. This places the script before the closing body tag on every page. Not all themes expose this option.
Page Builder HTML Element
For Elementor, Divi, or similar builders, paste the full embed code into an HTML element on the specific page where you want the widget. The widget will only appear on that page.
Add the Vapi widget script and element
Two pieces of code go into your WordPress site: the CDN script that loads the widget library, and the <vapi-widget> element that configures the widget with your credentials.
Paste the following block where your chosen method allows. The script tag loads the widget library. The <vapi-widget> tag mounts the widget with your public key and assistant ID.
Replace your-public-key with the Public API Key you copied from the Vapi dashboard. Replace your-assistant-id with the Assistant ID you copied from the Assistants page. Leave the quotes intact around each value.
The mode attribute accepts voice for voice-only conversations or chat for text-only conversations. The theme attribute accepts light or dark. Both attributes are optional and can be changed at any time.
Need a Vapi Account First?
Create a free Vapi account, configure an assistant, and copy your Public API Key and Assistant ID. The widget install takes under 30 minutes once your credentials are ready.
Create Your Vapi AccountConfigure widget mode and appearance
The widget supports voice mode, chat mode, and a hybrid mode that allows both. You can also customize colors, sizing, and labels to match your site design.
Voice mode only: Best for phone-first businesses where you want visitors to talk to the agent rather than type.
Chat mode only: Best for sites where visitors prefer text-based interaction or where voice is not practical.
Custom accent color: Add the color-accent attribute with a hex value to match your brand. The default accent is blue.
Test the widget on your live site
After saving your changes, open your WordPress site in a browser. A floating widget button should appear in the corner of the viewport. Click it and grant microphone permission when prompted. The widget will connect the call to your Vapi assistant.
If the widget appears but the call does not connect, check the browser console for error messages. A 400 error typically means either the public key or the assistant ID is incorrect, or the assistant is not configured to accept web calls. A network error typically means a firewall or content security policy is blocking the connection to Vapi’s servers.
If the widget does not appear at all, move to the troubleshooting section below.
Common issues and how to resolve them
The following issues account for the majority of widget install failures on WordPress. Work through them in order if your widget is not appearing or not connecting.
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Widget does not appear | Script not loaded or cached page | Clear your WordPress cache and browser cache. Verify the script tag is present in the page source by viewing page source and searching for vapi-ai/client-sdk-react. |
| Widget appears but click does nothing | JavaScript conflict or incorrect credentials | Open the browser console. Look for 400 errors (credentials) or JavaScript errors from other plugins. Temporarily deactivate other plugins to isolate the conflict. |
| Widget loads only on some pages | Page-specific embed method | If you used the page builder HTML element method, the widget only loads on that page. Switch to a Code Snippet plugin or theme footer injection to load the widget site-wide. |
| Call does not connect | Assistant not configured for web calls | Verify in the Vapi dashboard that your assistant is published and configured to accept web calls. Check that the assistant ID matches the one in your widget code. |
| Microphone permission blocked | Browser or site security settings | Ensure your site is served over HTTPS. Browsers block microphone access on HTTP pages. Check the browser’s site permissions for microphone access. |
| Widget position conflicts with other elements | CSS conflicts from theme or plugins | The widget renders in a fixed position by default. If another floating element overlaps it, adjust the z-index in your theme CSS or reposition the other element. |
| Widget not responsive on mobile | Theme or container CSS constraints | Verify that your theme does not apply fixed positioning or overflow constraints to the widget container. The widget inherits some styling from the parent page. |
If the issue persists after working through the table, verify that the public key and assistant ID are correct by re-copying them from the Vapi dashboard. A single missing character causes the widget to fail silently.
Trigger the widget from a custom button
You can open the widget from any button or link on your page by simulating a click on the widget element. This is useful if you want a specific call-to-action button to launch the voice agent rather than relying only on the floating widget button.
Add an ID to your custom button and add a small JavaScript snippet that triggers the widget click. The widget must already be loaded on the page for this to work.
If the widget element uses a shadow DOM, you may need to reference the widget’s internal button instead. Check the Vapi documentation for the current selector if the direct click does not work.
Connect the widget to GoHighLevel for CRM data capture
The Vapi widget handles the voice conversation. To capture the data from that conversation into a CRM, you connect Vapi to GoHighLevel via webhooks. When a call ends, Vapi sends a webhook to GoHighLevel with the conversation transcript and any structured data the assistant captured.
GoHighLevel receives the webhook, creates or updates the contact record, and triggers follow-up workflows based on the call outcome. This is the same architecture we deploy in production for after-hours coverage, document processing, and multi-location operations.
Our free blueprints document the full webhook configuration pattern. Each blueprint includes the payload structure, custom field mapping, and workflow triggers needed for the integration.
Ready to Connect Vapi to Your CRM?
Start with GoHighLevel as your CRM foundation. The blueprints walk through the full webhook configuration from Vapi to GoHighLevel.
Self-directed or managed deployment
This guide covers the self-directed path. If you want Agentix Logic to build and manage the full stack for you, the managed track includes widget installation, assistant configuration, webhook mapping, and ongoing tuning.
Blueprint Track
You build the stack yourself using our open blueprints and this guide. Best for teams with some technical capability.
- Purchase Vapi and GoHighLevel directly through our affiliate links.
- Install the widget using this guide.
- Configure the assistant and CRM webhooks using our blueprints.
- Full ownership of your infrastructure and data.
- Pay only the standard platform usage fees.
Done-For-You Managed Deployment
Agentix Logic installs the widget, configures the assistant, maps the webhooks, and maintains the system.
- Widget installation on your WordPress site.
- Voice agent build with custom conversation logic and brand voice.
- GoHighLevel webhook mapping for call data capture.
- Ongoing prompt engineering and logic refinements.
- Infrastructure usage bundled into a single monthly statement.
Common Questions About the Vapi Widget on WordPress
Can I use the Vapi widget without a developer?
Yes. The widget installs through a Code Snippet plugin or your theme’s footer injection. You paste the script tag and the widget element with your public key and assistant ID. No coding is required beyond copy and paste.
Where should I place the Vapi widget script on WordPress?
Place the CDN script and the vapi-widget tag in your site footer, ideally just before the closing body tag. This ensures the widget loads on every page without blocking page rendering. Code Snippet plugins and theme footer injection both handle this correctly.
The widget is not appearing on my WordPress site. What should I check?
Check for JavaScript conflicts with other plugins, clear your WordPress and browser cache, confirm you are using the Public API Key and not the private key, and verify the assistant ID is correct. Also check the browser console for 400 errors.
Can I trigger the Vapi widget from a custom button?
Yes. Add an ID to your button and use JavaScript to simulate a click on the widget element. The widget must already be loaded on the page for this to work. The advanced section of this guide includes the code.
Does the Vapi widget work with page builders like Elementor?
Yes. Paste the full embed code into an HTML element within Elementor. Make sure visibility conditions and animation effects on the HTML element are not interfering with the widget’s functionality. If the widget loads only on that page, switch to a site-wide footer injection method instead.
Is my API key safe in the widget code?
Yes. The Vapi Public API Key is designed to be exposed in client-side code. It is scoped to the specific assistant and permissions you configure. Never place your private API key in the widget code.
How do I capture call data into my CRM?
Connect Vapi to GoHighLevel via webhooks. When the call ends, Vapi sends the transcript and captured data to GoHighLevel, which creates or updates the contact record and triggers follow-up workflows. Our free blueprints document the full webhook configuration.
Ready to Deploy Your Own Voice Widget?
Create your Vapi account, configure an assistant, and install the widget using this guide. Or hear the production voice agent first on our live demo page.