HaulHQ Bridge

Descripziun

HaulHQ Bridge connects your WordPress site to your HaulHQ account. Add your services, dumpster rentals, reviews, and booking tools to any page using simple shortcodes.

Features:

  • AI chatbot widget for lead capture and instant pricing
  • Product grid and detail shortcodes with Schema.org markup
  • Service listing shortcodes with price ranges
  • Review display with star rating rich snippets
  • Service area listing for local SEO
  • Booking widget embed
  • Form integration (Gravity Forms, WPForms, Contact Form 7)
  • Automatic cache invalidation when you update products

Requirements:

  • A free HaulHQ account (sign up here)
  • Your HaulHQ API key (found in Settings > API Keys)

External Service

This plugin connects to HaulHQ, a third-party software-as-a-service platform, to provide its features. HaulHQ is required for the plugin to function: the plugin sends and receives data from the HaulHQ API to display your products, services, reviews, service area, and booking and chatbot widgets, and to forward leads captured on your site.

What is sent, and when:

  • On every page that uses a HaulHQ shortcode or widget: your plugin API key is sent to the HaulHQ API to retrieve your catalog, services, reviews, and service area content for display. No visitor personal data is sent for these read requests.
  • When a visitor submits a connected form or the chatbot/booking widget: the contact details they provide (such as name, email, phone, and message) are sent to the HaulHQ API so the lead can be recorded in your HaulHQ account. The chatbot and booking widgets are loaded from HaulHQ in an iframe and may set cookies as described in the HaulHQ privacy policy.
  • Cache invalidation: HaulHQ may send a signed webhook to your site to refresh cached catalog data when you change products in HaulHQ.
  • Google Ads conversion tracking (optional): if you configure a Google Ads Conversion ID in your HaulHQ dashboard, the plugin loads Google’s gtag.js library from googletagmanager.com and reports conversion events to Google Ads when visitors submit a form, book, or contact the chatbot. This is governed by Google’s privacy policy (https://policies.google.com/privacy). Nothing from Google is loaded if you do not configure a Conversion ID.

The service is provided by HaulHQ LLC. By using this plugin you agree to HaulHQ’s terms and privacy policy:

  • Terms of Service: https://haulhq.app/terms
  • Privacy Policy: https://haulhq.app/privacy

Usage

Display your products (dumpsters, trailers, etc.):
[haulhq_products type=“equipment“]

Display a single product detail page:
[haulhq_product slug=“20-yard-dumpster“]

Display your junk removal services:
[haulhq_services]

Display customer reviews with star ratings:
[haulhq_reviews]

Display your service area for local SEO:
[haulhq_service_area]

Add the AI chatbot:
The chatbot is not a shortcode. Turn it on in Settings > HaulHQ Bridge („Enable chat widget“)
and it appears site-wide as a floating widget on every page — there is nothing to paste.
Its behavior (including the after-hours-only option) is configured in your HaulHQ dashboard
under Settings > Chatbot.

Add the booking widget:
[haulhq_booking]

Add the quote & booking form (the main lead form):
[haulhq_form]
The visitor checks their zip, picks a load size for an instant price, then books a pickup or
requests a written estimate. Optional attributes: height="700" to set the initial iframe
height, show_price="false" to ask for contact details before showing the price (blank uses
your Settings > Quote Form default), and form="standard" for the single-screen variant.
A „HaulHQ Lead Form“ block is also available in the block editor.

Show your before/after photos on an existing page:
[haulhq_gallery]
Optional attributes: limit="6" for how many photos, and heading="none" to render no
heading when the page already has one.

Give the photos a dedicated gallery page:
[haulhq_gallery_page]
Shows all featured before/after photos as stacked cards. Optional attributes: columns="3",
counter=“false“ to hide the „N projects“ count, and heading="none" to suppress the heading.

Add a „Check Availability“ zip CTA anywhere (header, page, widget area):
[haulhq_zip_cta]
Optional attributes: theme="dark" for dark backgrounds, label="Get My Price" to change the button text, color="#f15a22" to set a custom button color, and layout="bar" for a compact single-row variant that fits in a site header. A visitor enters their zip and the booking flow opens in a pop-up with the zip already answered. A „HaulHQ Zip CTA“ block is also available in the block editor.

Compact header bar:
[haulhq_zip_cta layout=“bar“]
The bar layout keeps the control under 35px tall so it sits inline in a header. Combine with theme="dark" on dark headers. The default layout="box" is unchanged.

For full shortcode documentation and attributes, visit Settings > HaulHQ > Shortcodes in your WordPress admin.

Blocks

This plugin provides 10 blocks.

  • HaulHQ Single Product One product's detail card: photos, specs, pricing and a booking button. Same output as the [haulhq_product] shortcode.
  • HaulHQ Photo Gallery Your top before/after job photos as stacked cards. Best inside an existing page. Same output as the [haulhq_gallery] shortcode.
  • HaulHQ Zip CTA A compact zip-code 'Check Availability' field that opens the HaulHQ booking flow with the zip already answered.
  • HaulHQ Customer Reviews Customer reviews with star ratings and review schema for Google. Same output as the [haulhq_reviews] shortcode.
  • HaulHQ Service Area The cities or zip codes you serve, with local-SEO schema. Same output as the [haulhq_service_area] shortcode.
  • HaulHQ Booking Widget The full booking form, embedded on this page. Same output as the [haulhq_booking] shortcode.
  • HaulHQ Service Listing Your junk removal and hauling services with pricing. Same output as the [haulhq_services] shortcode.
  • HaulHQ Photo Gallery Page All your featured before/after photos, for a dedicated gallery page. Same output as the [haulhq_gallery_page] shortcode.
  • HaulHQ Product Grid Your dumpsters and equipment in a grid or list, with specs, pricing and a booking button. Same output as the [haulhq_products] shortcode.
  • HaulHQ Lead Form The quote request form customers fill in to become a lead. This is the form most operators want on their site.

Installaziun

  1. In your WordPress admin, go to Plugins > Add New and search for „HaulHQ“, then click Install Now (or upload the haulhq-bridge folder to /wp-content/plugins/)
  2. Activate the plugin through the Plugins menu
  3. Go to Settings > HaulHQ
  4. Enter your API key and click Save
  5. Add shortcodes to your pages (see Usage below)

FAQ

Is HaulHQ free?

Yes. HaulHQ has no monthly subscription. You pay $1.50 per completed job, capped at $149/mo.

Do I need a HaulHQ account?

Yes. Sign up for free at dashboard.haulhq.app/signup, then enter your API key in the plugin settings.

Will this slow down my site?

No. Product data is cached locally and refreshed hourly (or instantly when you update products in HaulHQ).

Where do I get my API key?

Log in to your HaulHQ dashboard at dashboard.haulhq.app, go to Settings > API Keys, and copy your key. Paste it into Settings > HaulHQ in your WordPress admin and click Save.

What data does the plugin send to HaulHQ?

For displaying content (products, services, reviews, service area), only your API key is sent to retrieve your account data — no visitor information. When a visitor submits a connected form or uses the chatbot or booking widget, the contact details they enter are sent to HaulHQ to record the lead in your account. See the „External Service“ section above for full details and links to HaulHQ’s terms and privacy policy.

Is this plugin tied to a paid service?

The plugin is free and open source (GPL). It requires a HaulHQ account to function. HaulHQ has no monthly subscription; it charges a per-completed-job fee with a monthly cap. SaaS-connected plugins like this are permitted on WordPress.org.

Does the plugin display any branding?

Yes. The chatbot, booking, and quote form widgets display a small „Powered by HaulHQ“ link. This appears inside the embedded widget, not on your page content. It is part of the free HaulHQ service.

Reviews

There are no reviews for this plugin.

Contributors & Developers

“HaulHQ Bridge” is open source software. The following people have contributed to this plugin.

Contributors

Translate “HaulHQ Bridge” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

1.7.7

  • „Book Now“ now opens the booking screen on your own page instead of sending the customer to another website. They stay where they were, and closing it puts them back exactly where they left off.
  • Your quote form now sits centred like every other HaulHQ block. It was the one block without a container of its own, which is why it sat off to one side on some themes. No custom CSS needed.
  • Product grids, service lists, photo galleries, the booking screen and the quote form now use the wider layout your theme already provides, instead of being squeezed into the narrow text column. Add width=“content“ to any of them to keep the old narrow width.
  • When a shortcode has nothing to show, logged-in editors now see a short message explaining why — a mistyped product slug, a hidden product, a missing API key. Visitors still see nothing.
  • Fixed: the quote form used to show „HaulHQ form is not configured“ to your customers when the API key was missing. That message is now for editors only.

1.7.6

  • Fixes „Book Now“ buttons returning a 404 page on sites running WooCommerce. WooCommerce reserves the product address parameter, so the booking link our buttons built was read as a request for a WooCommerce product, found nothing, and showed a Not Found page instead of your booking form. The link now uses haulhq_product, which nothing else claims. If you run WooCommerce and your Book Now buttons were dead, this is why.
  • Older links using the previous product parameter are still understood, so anything you published by hand keeps working.

1.7.5

  • Ad tracking: tightened the length limits on the optional ad-group and match-type parameters to match the documented values. No effect on Google Ads click tracking, which was already working.

1.7.4

  • Fixes 1.7.3, where the new ad-tracking script did not load at all. Update to this version; 1.7.3 tracked nothing.
  • Google Ads clicks are now tracked on your lead forms. Google’s auto-tagging (on by default) adds a gclid to your ad URLs and nothing else, so forms that only looked for utm_ tags recorded nothing at all from paid clicks. The form, booking and chat embeds now carry gclid and your campaign tags through to the lead, and you’ll see the source on the lead in your HaulHQ dashboard.
  • Ad tracking now survives browsing. If someone arrives from an ad, reads your pricing page, then comes back and submits, the click is still credited. Nothing is stored unless an ad parameter was actually present, nothing personal is kept, and it clears when the browser tab closes.
  • Nothing to configure. This works the moment you update, on every form, with no settings to find and no fields to add to your pages.

1.7.2

  • The quote & booking form is now a block too. Search the inserter for „HaulHQ Lead Form“ (or browse the HaulHQ category) to drop your main lead form on a page without typing a shortcode. It renders from the same code as [haulhq_form], so the output is identical, and the shortcode keeps working exactly as before. Height, form style (step-by-step or one screen) and the price-display override are all in the block sidebar.

1.7.1

  • Reviews shortcode: removed the review and rating structured data (schema.org markup) from [haulhq_reviews]. Google’s policy excludes self-serving reviews for a business on its own site, so the markup was never eligible for star rich results and risked being treated as spammy structured data; the stars you want in Google come from your Google Business Profile. Your visible reviews, summary and star display are unchanged. Also removed an anonymous LocalBusiness wrapper that could conflict with the business schema your theme or SEO plugin already declares.

1.7.0

  • Every shortcode is now also a Gutenberg block. Search the block inserter for „HaulHQ“ (or browse the new HaulHQ category) to add your product grid, single product, services, reviews, service area, booking form, photo galleries, and zip CTA without touching a shortcode. Blocks are server-rendered from the exact same code as the shortcodes, so output is identical, and every existing shortcode keeps working unchanged.

1.6.5

  • Chat widget: closing the chat now snoozes the auto-open „attention grab“ for 24 hours no matter how the chat was opened. Previously only dismissing an auto-opened chat did, so a visitor who opened the chat themselves and closed it got popped at again on the next page. The launcher button is unaffected and can always be tapped to reopen the chat.

1.6.4

  • Services shortcode: [haulhq_services] now respects your business verticals like [haulhq_products] always has. A dumpster-rental-only business no longer prints service listings that its HaulHQ site correctly hides.
  • Chat widget: you can now hide the chat launcher on specific pages. Add page paths under Settings > Chatbot in your HaulHQ dashboard („Hide the chat widget on these pages“) and the widget stays off those pages, including ad-click URLs with tracking parameters. No list configured means the widget shows everywhere, as before.

1.6.3

  • Chat widget: the after-hours chatbot (when „show only after hours“ is enabled) now reliably hides its launcher button during business hours. The launcher always follows the chat content, so an older cached copy of the widget script can never leave a visible-but-empty button on the page. Updating the plugin also refreshes the widget script so any stale cached copy is replaced.

1.6.2

  • Quote form: new optional form="standard" attribute on [haulhq_form] renders a single-screen lead-capture form (zip, name, phone, optional email, description, and photos) with no size or price step. Leave the attribute off (or use form="zip") to keep the default multi-step quote flow unchanged.

1.6.1

  • Gallery: before/after thumbnails now display on first page load even when a caching plugin’s image lazy-loader (Breeze, WP Rocket, LiteSpeed Cache, and similar) rewrites image tags. Thumbnails are marked to skip lazy loading, and the gallery script restores any image a lazy-loader still blanks. No per-site exclusion configuration needed. Other images on the page keep lazy loading normally.

1.6.0

  • Compliance overhaul for the WordPress.org plugin directory review.
  • Removed the Custom CSS setting. Use Appearance > Customize > Additional CSS instead; if you had saved CSS, a one-time notice on the HaulHQ settings page shows it for copying.
  • All iframe resize/scroll listeners moved from inline scripts to a single enqueued script (haulhq-frames.js) that only honors messages from your configured HaulHQ embed origin.
  • Hardened the public haulhq/v1/lead REST endpoint: honeypot check, per-IP rate limiting, server-side contact validation, optional REST nonce support (X-WP-Nonce or _wpnonce, action wp_rest).
  • Uninstall now also removes the auto-configure flag, tracking-config transient, and rate-limit transients.

1.5.17

  • Gallery: the before/after gallery ([haulhq_gallery] and [haulhq_gallery_page]) never renders a stack with a missing photo. A set with only one half (e.g. a „before“ with no matching „after“) is skipped instead of showing a broken empty image. Prevents a stale cache from resurfacing a half-populated set on your public site.

1.5.16

  • Zip CTA: [haulhq_zip_cta] accepts an optional booking_url attribute (e.g. [haulhq_zip_cta booking_url="/book-online/"]). When set, submitting a zip sends the visitor to that page with their zip carried in the URL (a real, trackable pageview) instead of opening a popup. The destination page must embed the [haulhq_form] shortcode; it lands the visitor already on the load-size step. UTM parameters are preserved. Leave the attribute off to keep the existing popup behavior. Also available on the „HaulHQ Zip CTA“ block.
  • Form: [haulhq_form] now reads a ?zip= value from the page URL (exactly 5 digits) and forwards it (plus any UTM parameters) into the booking form, so /book-online/?zip=85001 opens the form on the load-size step. Invalid zips are ignored.

1.5.15

  • Form: [haulhq_form] accepts an optional show_price attribute (show_price="false" to capture contact before revealing the estimate, show_price="true" to force prices on). Omit it to use your dashboard default (Settings > Quote Form > „Show prices on the form“). Lets you A/B price-gated vs price-shown forms on different pages.

1.5.14

  • Chatbot: new „After-Hours Chatbot“ option (Settings > Chatbot in your HaulHQ dashboard). When enabled, the floating chat widget appears only outside your business hours so daytime visitors reach your team directly. Open/closed is computed in the browser from your schedule + timezone, so it flips exactly at open/close. If no hours are set, the widget stays always-on. Off by default.

1.5.13

  • Admin: documented the Zip CTA layout attribute (box / bar) in the Shortcodes reference + builder (Settings > HaulHQ Bridge > Shortcodes), so the header-bar variant is discoverable. No front-end changes.

1.5.12

  • Zip CTA: new layout="bar" attribute (and a Layout control on the block) renders a compact single-row variant, made to drop into a site header. The control is ~35px tall on desktop and grows to ~44px on phones so it stays comfortably tappable. The default layout="box" is unchanged.

1.5.11

  • Zip CTA: added left padding inside the zip field so the location pin no longer overlaps the placeholder/typed text. Padding is enforced so host themes can’t crowd it back.

1.5.10

  • Zip CTA: the location pin now sits inside the zip field, and a new color="#f15a22" attribute sets a custom button color.
  • Removed the duplicate [haulhq_book] shortcode (use [haulhq_booking] for the equipment/dumpster rental widget).
  • Renamed the [haulhq_form] entry in the admin Shortcodes tab to „Junk Quote & Booking Form“ with an accurate description (it was mislabeled „Legacy“).

1.5.9

  • Added the new Zip Code CTA to the admin Shortcodes reference + builder (Settings > HaulHQ Bridge > Shortcodes), so it’s discoverable and copy-pasteable alongside the other shortcodes. No front-end changes.

1.5.8

  • New [haulhq_zip_cta] shortcode and matching „HaulHQ Zip CTA“ block: a compact „Check Availability“ zip field you can place anywhere (header, page, or widget area). A visitor enters their zip and the booking flow opens in a pop-up with the zip already filled in, so they start on the load-size step. Supports theme="dark" and a custom button label.

1.5.7

  • Removed the redundant Plugin URI header (it duplicated the Author URI). No functional changes.

1.5.6

  • Set an explicit version flag on the Google gtag.js script enqueue so it no longer triggers a Plugin Check warning. Updated the plugin description and search tags. No functional changes.

1.5.5

  • The chatbot attention grab (auto-open after a delay) now respects a 24-hour cooldown after a visitor closes it. Previously it reopened on every page load even after being dismissed. Manually opening or closing the chat is unaffected.

1.5.4

  • Added Google Ads conversion tracking. Configure your Conversion ID and labels in your HaulHQ dashboard (Settings > Tracking & Ads) and the plugin injects gtag.js and reports conversions when visitors submit the quote form, complete a booking, or give the chatbot their contact info. Native WordPress form submissions (Gravity Forms, WPForms, Contact Form 7) also report as conversions. No scripts are loaded for sites without tracking configured.

1.5.3

  • Attention grab delay now reads the live setting from your HaulHQ dashboard (Settings > Chatbot) instead of a separate plugin value, so changes take effect without reconfiguring the plugin. Made the auto-open reliable on mobile browsers. Add ?haulhq_debug=1 to a page URL to log widget timing to the browser console.

1.5.2

  • WordPress.org directory submission prep: added GPL license headers to all PHP files, added a LICENSE file, added an External Service disclosure section and expanded FAQ in the readme, and bumped the tested-up-to version to WordPress 7.0. No functional changes.

1.5.1

  • Attention grab now opens the chat window after the configured delay instead of bouncing the button. Set the delay to 0 to disable. Removed the bounce animation.

1.4.0

  • Plugin distribution: downloadable ZIP from HaulHQ dashboard (Settings > WordPress)
  • Dashboard shows API key, connection status, site URL, webhook secret, and installation guide
  • Build script for packaging plugin as installable WordPress ZIP

1.3.0

  • Admin page redesigned with 4-tab layout (Connection, Shortcodes, Styling, Cache)
  • Visual shortcode builder with AJAX preview rendering
  • Styling controls: default styles toggle, CTA color pickers, custom CSS
  • Cache management: status badge, TTL dropdown, clear cache button
  • URL hash deep linking for admin tabs

1.2.0

  • Webhook cache invalidation: HaulHQ SaaS sends HMAC-signed POST to clear transient cache on product changes
  • REST endpoint at /wp-json/haulhq/v1/cache-clear with HMAC-SHA256 validation and 5-minute replay protection
  • Manual „Clear Cache“ button on admin settings page
  • Webhook secret auto-generated on activation, displayed read-only for copy-paste into HaulHQ dashboard

1.1.0

  • New shortcode library with full Schema.org markup (Product, Service, AggregateRating, GeoCircle)
  • Shared catalog client with singleton pattern and transient caching
  • Product grid/list with detail_url linking, specs, CTA buttons
  • Single product detail view with image gallery and specs table
  • Service listing with price ranges and Schema.org Service markup
  • Service area display with zip codes and GeoCircle schema
  • Booking widget shortcode with service pre-selection
  • BEM-prefixed responsive CSS (mobile, tablet, desktop breakpoints)
  • CTA button JavaScript with chatbot/booking widget integration

1.0.0

  • Security hardening: masked API key with reveal/copy, capability checks, allowlist validation
  • Added Quick Start shortcode reference on admin page
  • Added PHP 8.0 and WordPress 6.0 version checks
  • Added uninstall.php for clean removal
  • Updated plugin branding and metadata
  • Rewritten readme.txt to WordPress.org standards

0.2.1

  • Added product catalog, services, reviews, and service area shortcodes
  • Added booking widget shortcode
  • Legacy SaaS URL auto-healing

0.1.0

  • Initial release
  • Chatbot widget embed
  • Gravity Forms, WPForms, CF7 integration
  • Generic REST endpoint for custom forms
  • Admin settings with connection test