Lead Widget

The Lead Widget is an embeddable React application that partners place on their website. It guides a homeowner from address entry through utility bill upload to a personalised savings report — qualifying the lead and routing it to the partner's CRM without any manual intervention.

User flow

Address entry

Google Maps autocomplete input. The widget geocodes the address and checks it against the partner's serving states. Out-of-market addresses trigger an exit screen — the lead is still captured.

Energy provider selection

Homeowner picks their electricity provider from a list fetched for their location. The right panel shows the partner's custom widget_info content configured in Vista.

Utility bill upload or manual entry

Upload a PDF/image of the bill, or enter monthly cost manually. The right panel shows "Did you know" facts from the selected utility provider.

Contact details

Homeowner provides name and email so the savings report can be delivered.

Confirmation

A "Check your email" confirmation screen is shown. The lead is simultaneously pushed to the partner's CRM.

Embedding the widget

The widget is a Next.js application served at a Metiss-hosted URL. Embed it on any partner web page using an <iframe>:

<iframe
  src="https://widget.metiss.ai?token=PARTNER_REFRESH_TOKEN"
  width="100%"
  height="600"
  frameborder="0"
></iframe>

Token: The tokenquery parameter is the partner's Firebase refresh token. The widget exchanges this for a short-lived ID token on load, then uses it to fetch the partner's configuration from the widget service. Obtain the token from the Vista Portal under Solar & Storage Design.

Partner configuration

The widget's behaviour is driven entirely by partner configuration fetched from the widget-service at load time. No hard-coded partner data exists in the widget code.

Config field	Effect on the widget
`logo_url`	Partner logo displayed in the top-left of the widget.
`serving_states`	List of US state codes the partner serves. Addresses outside these states trigger the exit screen.
`roof_types`	Roof type options shown during the address confirmation step.
`widget_info`	HTML content shown in the right panel on the energy provider selection step. Configured per partner in Vista.

All of these are managed in Vista under Admin Configurations → Markets and the organisation profile.

Out-of-market behaviour

If the homeowner's address falls outside the partner's serving states, the widget transitions to an exit screen rather than the normal flow. The lead is still captured (name and email) so the partner can follow up when they expand into that area.

Technology

Concern	Technology
Framework	Next.js (React)
Maps & geocoding	Google Maps JavaScript API (`@googlemaps/js-api-loader`) — address autocomplete and lat/lng geocoding.
Auth	Firebase refresh token passed as a URL query param; exchanged for an ID token via `authenticator-service`.
Partner config	Fetched from `widget-service/widget-info` on load using the ID token.
Bill upload	PDF or image upload passed to `utility-bill-service` for AI extraction.

API calls

Endpoint	When called
`POST /v1/authenticator-service/refresh-token`	On load — exchanges the refresh token for an ID token.
`GET /v1/widget-service/widget-info`	After auth — fetches partner logo, serving states, roof types, and widget info content.
`GET /v1/widget-service/utility-providers`	After address confirmed — fetches utility providers for the homeowner's location.
`POST /v1/utility-bill-service/upload`	When the homeowner uploads a bill — sends the file for AI extraction.