Customize and Embed Your Bayou Onboarding Widget Effectively

Integrate Bayou’s pre-built onboarding flow directly into your product so customers can link their utility accounts in seconds—no redirects required. From there, use the Bayou utility API to pull customer utility data.

This guide covers brand customization, script installation, event handling, and common errors.

1. Brand the Widget to Match Your UI

Head to Dashboard → Settings and update three fields:

• Company name – The name shown to users during authorization.
• Primary color – Paste a HEX value to set the button and link color.
• Logo – Upload a PNG or JPG to swap the Bayou logo for your own.

Save your edits and refresh the embed to see the new styling.

2. Add the Bayou JavaScript Library

Drop the script tag onto any page that should host the form.

<!-- Production -->
<script src="https://js.bayou.energy/v1"></script>

<!-- Staging -->
<script src="https://js.staging.bayou.energy/v1"></script>

Tip: “v1” references the component release, not the REST API version.

3. Mount the Onboarding Form

Place the snippet below in your front-end code (React, Vue, vanilla JS—any framework works). Replace each placeholder with real values:

Bayou.loadOnboardingForm(
  document.getElementById('<ELEMENT_ID>'),
  '<COMPANY_ID>',       // Find this in Dashboard → Settings
  '<ONBOARDING_TOKEN>', // Create via GET /customers/{id}
  (event) => {
    switch (event.type) {
      case 'customerHasAuthenticated':
        alert('Utility account linked!');
        break;
      case 'customerEnteredInvalidCredentials':
        alert('Credentials incorrect. Try again.');
        break;
      case 'customerEnteredInvalidMFAChallenge':
        alert('MFA verification failed.');
        break;
      // Legacy but still emitted
      case 'bayouCustomerFinishedOnboarding':
        alert('Onboarding complete.');
        break;
    }
  }
);

Current Event Payloads

• customerHasAuthenticated
• customerEnteredInvalidCredentials
• customerEnteredInvalidMFAChallenge
• (deprecated) bayouCustomerFinishedOnboarding

Always inspect event.type; Bayou may introduce additional events.

4. Handle Errors Gracefully

loadOnboardingForm() throws descriptive errors you can catch and display:

• InvalidElementError – Target container isn’t a valid DOM node.
• CompanyIdMissingError / CompanyIdNotAnInteger – Company ID absent or not numeric.
• OnboardingTokenMissingError – Token not supplied.
• InvalidOnboardingTokenError – Token malformed or looks like a URL.
• InvalidOnboardingTokenFormatError – Token fails regex validation.

Wrap the call in try…catch to surface helpful messages instead of silent failures.

5. Local Development Gotchas

Chrome and Safari block script execution from file:// paths.

Spin up a lightweight server—python3 -m http.server 8000 or similar—and visit http://localhost:8000 to test.

Firefox usually renders fine from the file system, but using a local URL is the safest bet.

Learn more about embedding the Bayou component in our API documentation.