Advanced configuration

Initial state

Control the widget’s initial visibility and open state:

import {
  provideZendeskWebWidget,
  withZendeskWebWidgetScript,
  withZendeskWebWidgetInitialState,
} from '@presencelearning/zendesk-web-widget';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZendeskWebWidget(
      withZendeskWebWidgetScript('YOUR_ZENDESK_KEY'),
      withZendeskWebWidgetInitialState({
        visible: true, // Show the widget button
        open: false, // Don't open the chat window automatically
      })
    ),
  ],
};

User authentication

Authenticate users with JWT tokens:

import {
  provideZendeskWebWidget,
  withZendeskWebWidgetScript,
  withZendeskWebWidgetAuth,
} from '@presencelearning/zendesk-web-widget';
import { inject } from '@angular/core';
import { AuthService } from './auth.service';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZendeskWebWidget(
      withZendeskWebWidgetScript('YOUR_ZENDESK_KEY'),
      withZendeskWebWidgetAuth(async () => {
        const authService = inject(AuthService);
        const token = await authService.getZendeskToken();

        return {
          token,
          userConversationFields: {
            userId: authService.currentUser.id,
            email: authService.currentUser.email,
          },
        };
      })
    ),
  ],
};

Configuration functions

provideZendeskWebWidget(...features)

Main provider function that sets up the Zendesk Web Widget with the specified features.

Parameters: Variable number of feature configurations. Returns: Provider[]

withZendeskWebWidgetScript(instanceId)

Provides the Zendesk widget script loader with your instance ID.

Parameters:

• instanceId: string — Your Zendesk instance key/ID

withZendeskWebWidgetInitialState(initialState)

Configures the initial state of the widget.

Parameters:

• initialState.visible?: boolean — Whether the widget button is visible
• initialState.open?: boolean — Whether the chat window is open

When this feature is omitted the defaults are { visible: true, open: false }.

withZendeskWebWidgetAuth(authMethod)

Provides authentication functionality for the widget.

Parameters:

• authMethod: () => Promise<UserData | null> — Async function returning user auth data

The returned shape is:

{
  token: string;
  userConversationFields?: Record<string, string>;
}

Neither that interface nor its function type alias is re-exported from the package entry point, so you cannot name the type in your own code — write the callback inline and let it infer.

userConversationFields returned here are captured and replayed by showAndOpen(). Fields passed to setFields() are not replayed.

Note also that a script load failure is logged and then resolves rather than rejecting, so it never blocks app initialization — provideZendeskWebWidget() will not surface the failure at bootstrap.

Complete example

app.config.ts

import { ApplicationConfig } from '@angular/core';
import {
  provideZendeskWebWidget,
  withZendeskWebWidgetScript,
  withZendeskWebWidgetInitialState,
  withZendeskWebWidgetAuth,
} from '@presencelearning/zendesk-web-widget';
import { inject } from '@angular/core';
import { AuthService } from './services/auth.service';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZendeskWebWidget(
      withZendeskWebWidgetScript('your-zendesk-instance-id'),
      withZendeskWebWidgetInitialState({
        visible: true,
        open: false,
      }),
      withZendeskWebWidgetAuth(async () => {
        const authService = inject(AuthService);

        if (!authService.isAuthenticated()) {
          return null;
        }

        const token = await authService.getZendeskJWT();

        return {
          token,
          userConversationFields: {
            userId: authService.user.id,
            email: authService.user.email,
            accountType: authService.user.plan,
          },
        };
      })
    ),
  ],
};

// support.component.ts
import { Component, inject, effect } from '@angular/core';
import { ZendeskWebWidget } from '@presencelearning/zendesk-web-widget';

@Component({
  selector: 'app-support',
  template: `
    <div class="support-widget">
      <button (click)="toggleWidget()">{{ widget.isOpen() ? 'Close' : 'Open' }} Support</button>

      @if (widget.isVisible()) {
        <button (click)="widget.hide()">Hide Widget</button>
      } @else {
        <button (click)="widget.show()">Show Widget</button>
      }
    </div>
  `,
})
export class SupportComponent {
  protected readonly widget = inject(ZendeskWebWidget);

  constructor() {
    // React to widget state changes
    effect(() => {
      console.log('Widget open state:', this.widget.isOpen());
    });
  }

  toggleWidget() {
    if (this.widget.isOpen()) {
      this.widget.close();
    } else {
      this.widget.showAndOpen();
    }
  }
}