index.d.ts

/** Gleap data region. */
export type GleapRegion = "eu" | "us";

export namespace Gleap {
  /** Options for `initialize`. */
  interface InitializeOptions {
    /**
     * Your Project ID (Gleap dashboard: Settings → Project → General).
     * Only needed when `initialize` is called with the options object alone.
     */
    projectId?: string;
    /**
     * How long (ms) a signed session stays signed before a new identify is needed.
     * The server never goes beyond the project's session max age.
     */
    sessionDuration?: number;
    /** @deprecated Has no effect: the ping it controlled no longer exists. */
    disablePing?: boolean;
  }
  /**
   * Initializes Gleap with your Project ID (formerly called "SDK key" or "API key";
   * the value is the same, existing keys keep working). Find it in the Gleap dashboard
   * under Settings → Project → General.
   *
   * `options.sessionDuration`: how long (ms) a signed session stays signed before a new
   * identify is needed. The server never goes beyond the project's session max age.
   * A signed session that runs out without a fresh token continues as a visitor.
   * A boolean second argument is the legacy `disablePing` flag and is still accepted
   * (the ping it controlled no longer exists, so it has no effect).
   *
   * @example Gleap.initialize("YOUR_PROJECT_ID");
   * @example Gleap.initialize({ projectId: "YOUR_PROJECT_ID", sessionDuration: 86400000 });
   */
  function initialize(
    projectId: string,
    options?: boolean | InitializeOptions
  ): void;
  function initialize(
    options: InitializeOptions & { projectId: string }
  ): void;
  function sendSilentCrashReport(
    description: string,
    priority?: "LOW" | "MEDIUM" | "HIGH",
    excludeData?: {
      customData?: Boolean;
      metaData?: Boolean;
      attachments?: Boolean;
      consoleLog?: Boolean;
      networkLogs?: Boolean;
      customEventLog?: Boolean;
      screenshot?: Boolean;
      replays?: Boolean;
    }
  ): void;
  function sendSilentCrashReportWithFormData(
    formData: {
      [key: string]: string;
    },
    priority?: "LOW" | "MEDIUM" | "HIGH",
    excludeData?: {
      customData: Boolean;
      metaData: Boolean;
      attachments: Boolean;
      consoleLog: Boolean;
      networkLogs: Boolean;
      customEventLog: Boolean;
      screenshot: Boolean;
      replays: Boolean;
    }
  ): void;
  function startClassicForm(
    formId: string,
    showBackButton?: boolean
  ): void;
  function startBot(botId: string, showBackButton?: boolean): void;
  function startConversation(showBackButton?: boolean): void;
  function attachCustomData(customData: any): void;
  function setTicketAttribute(key: string, value: string): void;
  function unsetTicketAttribute(key: string): void;
  function clearTicketAttributes(): void;
  function setCustomData(key: string, value: string): void;
  function removeCustomData(key: string): void;
  function clearCustomData(): void;
  function playSound(play: boolean): void;
  function destroy(): void;
  function showAiChatbar(): void;
  function hideAiChatbar(): void;
  function askAI(question: string, showBackButton?: boolean): void;
  function setAiChatbarQuickActions(quickActions: string[]): void;
  function startAgent(
    agentId: string,
    options?: { context?: any; initialQuestion?: string; initialMessage?: string }
  ): void;
  function isOpened(): boolean;
  /**
   * Sets the data region your Gleap project lives in. Call before initialize.
   * Defaults to "eu". The value is case-insensitive; an unknown value logs a
   * console warning and changes nothing.
   *
   * Sets three hosts at once:
   * - eu: apiUrl `https://api.gleap.io`, wsApiUrl `wss://ws.gleap.io`, realtimeHost `sockets.gleap.io`
   * - us: apiUrl `https://api.us.gleap.ai`, wsApiUrl `wss://ws.us.gleap.ai`, realtimeHost `sockets.us.gleap.ai`
   *
   * Order rule (last call wins): setApiUrl / setWSApiUrl / setRealtimeHost
   * called AFTER setRegion override that single host; setRegion called after
   * them overrides all three region hosts. The static widget hosts
   * (setFrameUrl, setBannerUrl, setModalUrl) are global and never changed by setRegion.
   */
  function setRegion(region: GleapRegion): void;
  /** Returns the current data region ("eu" unless setRegion was called). */
  function getRegion(): GleapRegion;
  function setApiUrl(apiUrl: string): void;
  function setWSApiUrl(wsApiUrl: string): void;
  /** Messenger realtime hostname, without protocol or path. Set before initialize. */
  function setRealtimeHost(realtimeHost: string): void;
  function setFrameUrl(frameUrl: string): void;
  function closeBanner(): void;
  function closeModal(): void;
  function setBannerUrl(bannerUrl: string): void;
  function setModalUrl(modalUrl: string): void;
  /**
   * Custom url for the `<gleap-agent-conversation>` iframe. Applies to elements
   * attached to the DOM after this call.
   */
  function setAgentConversationUrl(agentConversationUrl: string): void;
  function setMaxNetworkRequests(maxRequests: number): void;
  function startNetworkLogger(): void;
  function setNetworkLogsBlacklist(networkLogBlacklist: string[]): void;
  function setNetworkLogPropsToIgnore(filters: string[]): void;
  /**
   * @deprecated Use registerAgentTool(name, handler) with a dashboard-defined
   * Frontend tool instead.
   */
  function registerAgentToolAction(
    callback: (toolAction: {
      name: string;
      params: Record<string, any>;
      result: any;
      message: string;
      toolCallId: string;
    }) => void
  ): void;
  /**
   * Register the handler for a Frontend tool defined on an AI agent in the
   * Gleap dashboard. The agent calls the handler with the configured
   * parameters and waits for its return value (string or JSON — JSON is
   * stringified). Thrown errors are caught and reported back to the AI.
   */
  function registerAgentTool(
    name: string,
    handler: (
      params: Record<string, any>
    ) => string | object | Promise<string | object>
  ): void;
  function registerCustomAction(
    customAction: (action: {
      name: string;
      /** The action's data (a message button's actionData), when it has some. */
      data?: any;
      /** The share token of the conversation the action was clicked in. */
      shareToken?: string;
    }) => void
  ): void;
  function log(message: string, logLevel?: "INFO" | "WARNING" | "ERROR"): void;
  /**
   * @deprecated Please use trackEvent instead.
   */
  function logEvent(name: string, data?: any): void;
  function trackEvent(name: string, data?: any): void;
  function setAppBuildNumber(buildNumber: string): void;
  function setAppVersionCode(versionCode: string): void;
  function setStyles(styles: {
    primaryColor: string;
    headerColor: string;
    buttonColor: string;
    backgroundColor: string;
    borderRadius?: number;
    buttonX?: number;
    buttonY?: number;
    buttonStyle?: string;
  }): void;
  function disableConsoleLogOverwrite(): void;
  function setLiveSite(isLiveSite: boolean): void;
  function enableShortcuts(enabled: boolean): void;
  function setLanguage(language: string): void;
  function preFillForm(data: object): void;
  /**
   * @deprecated Define Frontend tools on your AI agent in the Gleap dashboard
   * and register their handlers via registerAgentTool(name, handler) instead.
   */
  function setAiTools(tools: {
    name: string;
    description: string;
    response?: string;
    executionType?: 'button' | 'auto';
    parameters?: {
      name: string;
      description: string;
      type: "string" | "number" | "boolean";
      required: boolean;
      enum?: string[];
    }[];
  }[]): void;
  function showTabNotificationBadge(showNotificationBadge: boolean): void;
  function attachNetworkLogs(networkLogs: string): void;
  /**
   * Call on logout. Clears the current contact, its identity token, the grant and auth tokens.
   * The JWT provider stays set.
   */
  function clearIdentity(): void;
  /**
   * Identifies the user with an identity token: an HS256 JWT signed by your backend with an
   * identity key (Settings → Security → Customer identity → Identity keys).
   * The `userId` (or `user_id`) claim names the user; every other claim lands on the
   * contact as signed data. Nothing else is sent. Kept in memory only.
   * Call it after login and on every page load of a logged-in user; no separate
   * `identify` call is needed.
   * A token that is not a JWT, has no userId or is over 4096 characters is refused
   * with a console warning and no request.
   * Never rejects; refusals are logged.
   * @see https://docs.gleap.ai/en/articles/709-customer-identity
   */
  function setUserJwt(token: string): Promise<void>;
  /**
   * Optional: sets a function that returns a fresh identity token from your backend.
   * Called when the current token expired, or before a renewal when it expires within
   * 5 minutes. Also restores the signed session after
   * a page reload: when the server reports Signed mode for an identified session without
   * a valid grant (no grant cookie) and no token was passed to `setUserJwt`, it is asked
   * once per page load and the user is identified with its token. Returning `null`
   * sends nothing; when the session's grant has expired, the user then continues as a
   * visitor. One call at a time, 10 s timeout, 30 s pause after a failure.
   * `null` removes the provider.
   */
  function setUserJwtProvider(provider: (() => string | null | Promise<string | null>) | null): void;
  /**
   * How long (ms) a signed session stays signed; the server never goes beyond the
   * project's maximum. Same as `initialize(projectId, { sessionDuration })`. `null` drops it.
   */
  function setSessionDuration(sessionDuration: number | null): void;
  /**
   * Stores per-user tokens for your API tools on the signed contact
   * (`{{session.authTokens.<name>}}`). Names: a letter followed by up to 39 letters,
   * digits, `_` or `-`. A `null` value removes a token. Kept in memory only and
   * sent again after the next signed identify on a new session. Needs `setUserJwt`.
   */
  function setAuthTokens(tokens: Record<string, string | null>): Promise<void>;
  function setTags(tags: string[]): void;
  /**
   * Hide notification cards, including cached or already-visible cards, without
   * hiding the support button or messenger. Reenable to show eligible cards again.
   */
  function setDisableInAppNotifications(
    disableInAppNotifications: boolean
  ): void;
  function setDisablePageTracking(
    disablePageTracking: boolean
  ): void;
  /**
   * Identifies the user by user id and contact data. Without a signature this is an
   * unsigned contact; to sign the user in, use `setUserJwt`.
   * @see https://docs.gleap.ai/en/articles/395-javascript-sdk-user-identity
   */
  function identify(
    userId: string,
    customerData: {
      name?: string | null;
      email?: string | null;
      phone?: string | null;
      value?: number | null;
      /** @deprecated Use `company` instead. */
      companyId?: string | null;
      /** @deprecated Use `company` instead. */
      companyName?: string | null;
      company?: { id: string | number; name?: string | null } | null;
      sla?: number | null;
      plan?: string | null;
      customData?: object | null;
      avatar?: string | null;
      createdAt?: Date | null;
    },
    /**
     * Older integrations pass the HMAC-SHA256 user hash here; it keeps working. An identity
     * token is accepted too, but `setUserJwt` is the way to sign in.
     * @see https://docs.gleap.ai/en/articles/16752008-upgrade-to-identity-tokens
     */
    userHash?: string
  ): void;
  function updateContact(
    customerData: {
      name?: string | null;
      email?: string | null;
      phone?: string | null;
      value?: number | null;
      /** @deprecated Use `company` instead. */
      companyId?: string | null;
      /** @deprecated Use `company` instead. */
      companyName?: string | null;
      company?: { id: string | number; name?: string | null } | null;
      sla?: number | null;
      plan?: string | null;
      avatar?: string | null;
      customData?: object | null;
    }
  ): void;
  function getInstance(): any;
  function open(): void;
  function openChecklists(showBackButton?: boolean): void;
  function openChecklist(checklistId: string, showBackButton?: boolean): void;
  function startChecklist(outboundId: string, showBackButton?: boolean, sharedKey?: string): void;
  function openNews(showBackButton?: boolean): void;
  function openNewsArticle(id: string, showBackButton?: boolean): void;
  function openConversations(showBackButton?: boolean): void;
  function startProductTour(tourId: string): void;
  function openConversation(
    shareToken?: string,
    showBackButton?: boolean
  ): void;
  function setUrlHandler(
    urlHandler: (url: string, newTab?: boolean) => void
  ): void;
  function openHelpCenter(showBackButton?: boolean): void;
  function openHelpCenterCollection(
    collectionId: string,
    showBackButton?: boolean
  ): void;
  function openHelpCenterArticle(
    articleId: string,
    showBackButton?: boolean
  ): void;
  function searchHelpCenter(term: string, showBackButton?: boolean): void;
  function openFeatureRequests(showBackButton?: boolean): void;
  function close(): void;
  function hide(): void;
  function setUseCookies(useCookies: boolean): void;
  /**
   * Sets the widget's color scheme, overriding the dashboard's "Color scheme"
   * setting, which applies until this is called. Only takes effect when "Adapt
   * to dark / light mode" is enabled in the dashboard; while it is disabled the
   * widget is never themed. "auto" follows the host app's dark/light mode (theme
   * classes/attributes like `class="dark"` or `data-theme="dark"`, the CSS
   * color-scheme, the page background, then the OS preference) and switches
   * live. "light"/"dark" force a scheme. Any other value (including the former
   * "default") is treated as "auto". Dark mode uses the dark colors set in the
   * dashboard (header colors, UI color, background) and the dark logo, header
   * image and composer glow set there; without dark colors the widget keeps
   * its normal colors.
   */
  function setColorScheme(
    colorScheme: "auto" | "light" | "dark",
    options?: {
      /** #rrggbb background used in light mode. Defaults to the dashboard background. */
      lightBackgroundColor?: string;
      /** #rrggbb background used in dark mode. Defaults to the dashboard's dark background. Also enables dark mode without dark colors in the dashboard. */
      darkBackgroundColor?: string;
    }
  ): void;
  function setEnvironment(environment: "dev" | "staging" | "prod"): void;
  /**
   * Env data keys (e.g. "currentUrl", "userAgent") that are removed before a
   * ticket is sent. Each call replaces the previous list.
   */
  function setEnvDataPropsToIgnore(propsToIgnore: string[]): void;
  /**
   * Stops (true) or resumes (false) collecting env data. While disabled,
   * tickets are sent without any env data.
   */
  function setDisableEnvData(disableEnvData: boolean): void;
  function setCSPNonce(nonce: string): void;
  function showFeedbackButton(show: boolean): void;
  function startFeedbackFlow(
    feedbackFlow: string,
    showBackButton?: boolean
  ): void;
  type SurveyFormat = "card" | "full" | "page";
  interface ShowSurveyOptions {
    /** card = corner popover (bottom sheet on phones), full = full screen, page = inline in `container`. Default: card. */
    format?: SurveyFormat;
    /** Values for the survey's hidden fields. */
    fields?: Record<string, string>;
    /** Signed personal-link token: attaches the response to that contact. */
    personalToken?: string;
    /** Page format: answer with the keyboard while focus is on the host page. */
    keyboard?: boolean;
    /** Element (or CSS selector) the page format renders into. Default: document.body. */
    container?: HTMLElement | string;
    /** Continue a started response where it was left. */
    resume?: boolean;
  }
  /**
   * Shows a survey. The legacy format strings ("survey", "survey_full", "survey_web") keep working.
   */
  function showSurvey(
    surveyId: string,
    formatOrOptions?: "survey" | "survey_full" | "survey_web" | string | ShowSurveyOptions
  ): void;
  /** Surveys 2.0 events (reported by the survey renderer; not fired for legacy surveys). */
  interface SurveyShownEvent {
    surveyId: string;
    version: number;
    format: SurveyFormat;
    responseId: string;
    /** true when a started response was continued (resume). */
    resumed: boolean;
  }
  interface SurveyStepViewedEvent {
    surveyId: string;
    version: number;
    responseId: string;
    /** Zero-based position of the question in the survey. */
    stepIndex: number;
    /** Question (block) key. */
    key: string;
    [key: string]: any;
  }
  interface SurveyAnsweredEvent {
    surveyId: string;
    version: number;
    responseId: string;
    [key: string]: any;
  }
  interface SurveyCompletedEvent {
    surveyId: string;
    version: number;
    responseId: string;
    endingId: string;
    /** Answers keyed by question key. */
    answers: Record<string, any>;
  }
  interface SurveyClosedEvent {
    surveyId: string;
    version: number;
    responseId?: string;
    /** Response status when closed (e.g. "in_progress", "completed"); none when nothing was answered. */
    status?: string;
  }
  /** The survey is visible. */
  function on(event: "survey-shown", callback: (data: SurveyShownEvent) => void): void;
  /** A question became visible. */
  function on(event: "survey-step-viewed", callback: (data: SurveyStepViewedEvent) => void): void;
  /** An answer was saved. */
  function on(event: "survey-answered", callback: (data: SurveyAnsweredEvent) => void): void;
  /** The last question was answered and an ending is shown. `outbound-sent` keeps firing as before. */
  function on(event: "survey-completed", callback: (data: SurveyCompletedEvent) => void): void;
  /** The survey was closed (by the user or after its ending). */
  function on(event: "survey-closed", callback: (data: SurveyClosedEvent) => void): void;
  function on(
    event:
      | "initialized"
      | "open"
      | "close"
      | "flow-started"
      | "checklist-loaded"
      | "checklist-step-completed"
      | "checklist-completed"
      | "agent-message-sent"
      | "agent-reply-received"
      | "agent-error"
      | "agent-conversation-created"
      | "agent-tool-executed"
      | string,
    callback: (data?: any) => void
  ): void;
  function sendAgentMessage(
    agentId: string,
    message: string,
    options?: {
      conversationId?: string;
      additionalContext?: Record<string, any>;
    }
  ): Promise<{
    runId: string;
    status: string;
    response: string;
    conversationId?: string;
    outcome?: { type: string };
  }>;
  function clearAgentConversation(): void;

  interface AgentChatMessage {
    id: string;
    role: 'user' | 'assistant';
    content: string;
    createdAt: string;
  }

  interface AgentChatState {
    messages: AgentChatMessage[];
    isExecuting: boolean;
    error: any;
    conversationId: string | null;
  }

  interface AgentChatOptions {
    /** The agent ID to talk to. */
    agentId: string;
    /** Additional context sent with every message to the AI. */
    context?: Record<string, any>;
    /** Resume an existing conversation by ID. */
    conversationId?: string;
    /** Called on every state change (messages, loading, error). */
    onChange?: (state: AgentChatState) => void;
    /** Called when the agent replies. */
    onReplyReceived?: (data: any) => void;
    /** Called on error. */
    onError?: (error: any) => void;
    /** Called when a new conversation is created. */
    onConversationCreated?: (conversationId: string) => void;
  }

  interface AgentChatInstance {
    /** Send a message to the agent. */
    sendMessage(content: string): Promise<void>;
    /** Clear all messages and start a new conversation. */
    clearMessages(): void;
    /** Update the context sent with future messages. */
    setContext(context: Record<string, any>): void;
    /** Get the current state snapshot. */
    getState(): AgentChatState;
    /** Destroy this instance and stop all callbacks. */
    destroy(): void;
  }

  /**
   * Create a headless agent chat instance.
   * Framework-agnostic — wire onChange to React setState, Vue ref, Svelte store, etc.
   *
   * @example
   * ```js
   * const chat = Gleap.createAgentChat({
   *   agentId: 'abc123',
   *   context: { page: '/billing' },
   *   onChange: ({ messages, isExecuting }) => { ... },
   * });
   * chat.sendMessage('Hello!');
   * ```
   */
  function createAgentChat(options: AgentChatOptions): AgentChatInstance;

  /**
   * The current session, including `gleapId`, `gleapHash` and `grant` (the signed-session
   * credential a signed identify returns; null when the session is not signed).
   */
  /**
   * The current session: the identified user's data (userId, name, email, phone, … as before) plus
   * gleapId/gleapHash and, on a Signed project, the session grant. Guests have no userId.
   */
  function getIdentity(): {
    userId: string;
    name?: string;
    email?: string;
    phone?: string;
    companyId?: string;
    gleapId: string | null;
    gleapHash: string | null;
    grant: string | null;
    [key: string]: any;
  };
  function isUserIdentified(): boolean;
  function setReplayOptions(options: {
    blockClass?: string | RegExp;
    blockSelector?: string;
    ignoreClass?: string | RegExp;
    ignoreSelector?: string;
    ignoreCSSAttributes?: string[];
    maskTextClass?: string | RegExp;
    maskTextSelector?: string;
    maskAllInputs?: boolean;
    maskInputOptions?: {
      password?: boolean;
      [key: string]: any;
    };
    maskInputFn?: (text: string, element: HTMLElement) => string;
    maskTextFn?: (text: string, element: HTMLElement | null) => string;
    slimDOMOptions?: {
      [key: string]: any;
    };
    dataURLOptions?: {
      [key: string]: any;
    };
    hooks?: {
      [key: string]: any;
    };
    packFn?: (events: any) => any;
    sampling?: any;
    recordCanvas?: boolean;
    recordCrossOriginIframes?: boolean;
    recordAfter?: 'DOMContentLoaded' | 'load';
    inlineImages?: boolean;
    collectFonts?: boolean;
    userTriggeredOnInput?: boolean;
    plugins?: {
      [key: string]: any;
    }[];
    errorHandler?: (error: Error) => void;
  }): void;
  /**
   * Enables or disables screenshots and screen recordings that teammates, AI agents or workflows
   * ask the customer for in the widget (default: enabled). While disabled, the widget offers
   * uploading a file instead. Can be called before initialize.
   */
  function setCaptureEnabled(enabled: boolean): void;
  /**
   * Enables or disables sending logs when teammates, AI agents or workflows request them, on their
   * own or along with a screenshot or screen recording (default: enabled). Only data a bug report
   * carries is sent: console and network logs, custom data, environment data and events. Can be
   * called before initialize.
   */
  function setRemoteLogCollectionEnabled(enabled: boolean): void;
}
export default Gleap;

// Custom element type declarations — makes <gleap-*> work in JSX without extra setup
// Covers both React 18 (global JSX) and React 19+ (React.JSX)
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'gleap-agent-conversation': any;
      'gleap-agent-input': any;
      'gleap-agent-profile-image': any;
      'gleap-agent-reply-bubble': any;
      'gleap-agent-user-bubble': any;
      'gleap-agent-typing-indicator': any;
      'gleap-agent-send-button': any;
      'gleap-agent-message-list': any;
      'gleap-checklist': any;
    }
  }
}

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'gleap-agent-conversation': any;
      'gleap-agent-input': any;
      'gleap-agent-profile-image': any;
      'gleap-agent-reply-bubble': any;
      'gleap-agent-user-bubble': any;
      'gleap-agent-typing-indicator': any;
      'gleap-agent-send-button': any;
      'gleap-agent-message-list': any;
      'gleap-checklist': any;
    }
  }
}