TypeScript definitions for Zendesk Web Widget, based on https://developer.zendesk.com/embeddables/docs/widget/introduction

zendesk-web-widget.d.ts

/* eslint-disable @typescript-eslint/unified-signatures */
/* eslint-disable @typescript-eslint/naming-convention */
interface ZendeskWidgetCommander {
  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#clear */
  (type: 'webWidget', command: 'clear'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#close */
  (type: 'webWidget', command: 'close'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#get-display */
  (type: 'webWidget:get', command: 'display'): unknown;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#hide */
  (type: 'webWidget', command: 'hide'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#identify */
  (
    type: 'webWidget',
    command: 'identify',
    data: {
      readonly name: string;
      readonly email: string;
      readonly organization?: string;
    },
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#logout */
  (type: 'webWidget', command: 'logOut'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#on-open */
  (type: 'webWidget:on', command: 'open', callback: () => void): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#on-close */
  (type: 'webWidget:on', command: 'close', callback: () => void): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#on-userevent */
  (
    type: 'webWidget:on',
    command: 'userEvent',
    callback: (userEvent: {
      readonly action: string;
      readonly properties: unknown;
      readonly category: string;
    }) => void,
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#open */
  (type: 'webWidget', command: 'open'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#prefill */
  (
    type: 'webWidget',
    command: 'prefill',
    data: {
      readonly name?: {
        readonly value: string;
        readonly readOnly?: boolean;
      };
      readonly email?: {
        readonly value: string;
        readonly readOnly?: boolean;
      };
      readonly phone?: {
        readonly value: string;
        readonly readOnly?: boolean;
      };
    },
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#reset */
  (type: 'webWidget', command: 'reset'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#setlocale */
  (type: 'webWidget', command: 'setLocale', locale: string): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#show */
  (type: 'webWidget', command: 'show'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#toggle */
  (type: 'webWidget', command: 'toggle'): void;

  /**
   * @see https://developer.zendesk.com/embeddables/docs/widget/core#updatepath
   * @see https://developer.zendesk.com/embeddables/docs/widget/chat#updatepath
   */
  (
    type: 'webWidget',
    command: 'updatePath',
    data: {
      readonly title?: string;
      readonly url?: string;
    },
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/core#updatesettings */
  (
    type: 'webWidget',
    command: 'updateSettings',
    settings: ZendeskWidgetSettings,
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/help_center#helpcentersetsuggestions */
  (
    type: 'webWidget',
    command: 'helpCenter:setSuggestions',
    options: {
      readonly url?: boolean;
      readonly search?: string;
      readonly labels?: readonly string[];
    },
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#chatsend */
  (type: 'webWidget', command: 'chat:send', message: string): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#get-chatischatting */
  (type: 'webWidget:get', command: 'chat:isChatting'): boolean;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#get-chatdepartment */
  (
    type: 'webWidget:get',
    command: 'chat:department',
    department: string | number,
  ): ZendeskChatDepartment | undefined;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#get-chatdepartment */
  (
    type: 'webWidget:get',
    command: 'chat:departments',
  ): readonly ZendeskChatDepartment[];

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#chatend */
  (type: 'webWidget:get', command: 'chat:end'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#on-chatconnected */
  (type: 'webWidget:on', command: 'chat:connected', callback: () => void): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#on-chatstart */
  (type: 'webWidget:on', command: 'chat:start', callback: () => void): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#on-chatend */
  (type: 'webWidget:on', command: 'chat:end', callback: () => void): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#on-chatstatus */
  (
    type: 'webWidget:on',
    command: 'chat:status',
    callback: (status: 'online' | 'away' | 'offline') => void,
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#on-chatdepartmentstatus */
  (
    type: 'webWidget:on',
    command: 'chat:departmentStatus',
    callback: (department: ZendeskChatDepartment) => void,
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#on-chatunreadmessages */
  (
    type: 'webWidget:on',
    command: 'chat:unreadMessages',
    callback: (count: number) => void,
  ): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#popout */
  (type: 'webWidget', command: 'popout'): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#on-chatpopout */
  (type: 'webWidget:on', command: 'chat:popout', callback: () => void): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#chataddtags */
  (type: 'webWidget', command: 'chat:addTags', tags: readonly string[]): void;

  /** @see https://developer.zendesk.com/embeddables/docs/widget/chat#chatremovetags */
  (
    type: 'webWidget',
    command: 'chat:removeTags',
    tags: readonly string[],
  ): void;
}

interface ZendeskChatDepartment {
  readonly id: number;
  readonly name: string;
  readonly status: unknown;
}

interface ZendeskUIString {
  [locale: string]: string;
}

interface ZendeskField {
  id: string | number;
  prefill: ZendeskUIString;
}

interface ZendeskWidgetSettings {
  /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#analytics */
  readonly analytics?: boolean;
  /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#cookies */
  readonly cookies?: boolean;
  /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#errorreporting */
  readonly errorReporting?: boolean;
  readonly webWidget: {
    readonly answerBot?: {
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#avatar */
      readonly avatar?: {
        readonly url?: string;
        readonly name?: ZendeskUIString;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#contactonlyafterquery */
      readonly contactOnlyAfterQuery?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#search */
      readonly search?: readonly string[];
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#suppress */
      readonly suppress?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#title */
      readonly title?: ZendeskUIString;
    };
    /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#authenticate */
    readonly authenticate?: {
      readonly chat?: {
        readonly jwtFn?: (callback: (jwt: string) => void) => void;
      };
      readonly jwtFn?: (callback: (jwt: string) => void) => void;
    };
    readonly chat?: {
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#concierge */
      readonly concierge?: {
        readonly avatarPath?: string;
        readonly name?: string;
        readonly title?: ZendeskUIString;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#connectonpageload */
      readonly connectOnPageLoad?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#departments */
      readonly departments?: {
        /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#departments.enabled */
        readonly enabled?: readonly string[];
        /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#departments.select */
        readonly select?: string;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#hidewhenoffline */
      readonly hideWhenOffline?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#menuoptions */
      readonly menuOptions?: {
        readonly emailTranscript?: boolean;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#notifications */
      readonly notifications?: {
        readonly mobile?: {
          readonly disable?: boolean;
        };
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#offlineform */
      readonly offlineForm?: {
        readonly greeting?: ZendeskUIString;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#prechatform */
      readonly prechatForm?: {
        readonly greeting?: ZendeskUIString;
        readonly departmentLabel?: ZendeskUIString;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#profilecard */
      readonly profileCard?: {
        readonly avatar?: boolean;
        readonly rating?: boolean;
        readonly title?: boolean;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#position */
      readonly position?: {
        /** @default 'right' */
        readonly horizontal?: 'left' | 'right';
        /** @default 'bottom' */
        readonly vertical?: 'top' | 'bottom';
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#suppress */
      readonly suppress?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#title */
      readonly title?: ZendeskUIString;
    };
    /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#color */
    readonly color?: {
      readonly theme?: string;
      readonly launcher?: string;
      readonly launcherText?: string;
      readonly button?: string;
      readonly resultLists?: string;
      readonly header?: string;
      readonly articleLinks?: string;
    };
    readonly contactForm?: {
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#attachments */
      readonly attachments?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#fields */
      readonly fields?: readonly ZendeskField[];
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#selectticketform */
      readonly selectTicketForm?: ZendeskUIString;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#subject */
      readonly subject?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#suppress */
      readonly suppress?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#ticketforms */
      readonly ticketForms?: ReadonlyArray<{
        readonly id: number;
        readonly fields?: ZendeskField[];
      }>;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#title */
      readonly title?: ZendeskUIString;
    };
    readonly contactOptions?: {
      readonly enabled?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#chatlabelonline */
      readonly chatLabelOnline?: ZendeskUIString;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#chatlabeloffline */
      readonly chatLabelOffline?: ZendeskUIString;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#contactbutton */
      readonly contactButton?: ZendeskUIString;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#contactformlabel */
      readonly contactFormLabel?: ZendeskUIString;
    };
    readonly launcher?: {
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#badge */
      readonly badge?: {
        /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#badge.label */
        readonly label?: ZendeskUIString;
        /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#badge.image */
        readonly image?: string;
        /**
         * @see https://developer.zendesk.com/embeddables/docs/widget/settings#badge.layout
         * @default 'image_right'
         */
        readonly layout?:
          | 'image_right'
          | 'image_left'
          | 'image_only'
          | 'text_only';
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#chatlabel */
      readonly chatLabel?: ZendeskUIString;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#label */
      readonly label?: ZendeskUIString;
      readonly mobile?: {
        /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#labelvisible */
        readonly labelVisible?: boolean;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#talklabel */
      readonly talkLabel?: ZendeskUIString;
    };
    readonly helpCenter?: {
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#chatbutton */
      readonly chatButton?: ZendeskUIString;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#filter */
      readonly filter?: {
        readonly category?: string;
        readonly section?: string;
        readonly label_names?: string;
      };
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#messagebutton */
      readonly messageButton?: ZendeskUIString;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#originalarticlebutton */
      readonly originalArticleButton?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#searchplaceholder */
      readonly searchPlaceholder?: ZendeskUIString;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#suppress */
      readonly suppress?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#title */
      readonly title?: ZendeskUIString;
    };
    /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#navigation */
    readonly navigation?: {
      readonly popoutButton?: {
        readonly enabled?: boolean;
      };
    };
    /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#offset */
    readonly offset?: {
      readonly horizontal?: string;
      readonly vertical?: string;
      readonly mobile?: {
        readonly horizontal?: string;
        readonly vertical?: string;
      };
    };
    readonly talk?: {
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#nickname */
      readonly nickname?: string;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#suppress */
      readonly suppress?: boolean;
      /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#title */
      readonly title?: ZendeskUIString;
    };
    /** @see https://developer.zendesk.com/embeddables/docs/widget/settings#zindex */
    readonly zIndex?: number;
  };
}

interface Window {
  /** @see https://developer.zendesk.com/embeddables/docs/widget/introduction#settings */
  zESettings?: ZendeskWidgetSettings;
  /** @see https://developer.zendesk.com/embeddables/docs/widget/introduction#commands */
  zE: ZendeskWidgetCommander;
}