@pipeback/pipeback-js

Official Pipeback JavaScript SDK - Works with React, Vue, Angular, Svelte, Next.js, Nuxt, and vanilla JavaScript.

Installation

npm install @pipeback/pipeback-js
# or
yarn add @pipeback/pipeback-js
# or
pnpm add @pipeback/pipeback-js

Quick Start

Auto-initialization (default)

import Pipeback from '@pipeback/pipeback-js';

const pipeback = Pipeback({
  workspaceId: 'YOUR_PIPEBACK_WORKSPACE_ID',
  init: true, // Optional: default is true
  user: {
    id: '9f7618a2',
    name: 'Paulo Castellano',
    email: '[email protected]',
    company: {
      id: '8f4618a2',
      name: 'Pipeback',
      website: 'pipeback.com'
    },
    attributes: {
      plan: 'pro',
      monthly_spend: 5000,
    }
  },
  callbacks: {
    onLoaded: () => console.log('Widget loaded!'),
    onOpen: () => console.log('Widget opened'),
    onClose: () => console.log('Widget closed'),
  }
});
// Automatically initializes!

// Control the widget
pipeback.open();
pipeback.close();
pipeback.show();
pipeback.hide();

Manual initialization

import Pipeback from '@pipeback/pipeback-js';

const pipeback = Pipeback({
  workspaceId: 'YOUR_PIPEBACK_WORKSPACE_ID',
  init: false, // Disable auto-initialization
  user: {
    id: '9f7618a2',
    name: 'Paulo Castellano',
    email: '[email protected]'
  }
});

// Initialize manually when ready
await pipeback.init();

// Now you can control the widget
pipeback.open();

Framework Examples

For framework-specific integration examples, see the examples/ directory:

• Vanilla JavaScript
• React
• Next.js
• Vue 3
• Nuxt 3
• Angular
• Svelte

API Reference

Configuration Options

interface PipebackConfig {
  workspaceId: string;           // Required: Your Pipeback workspace ID
  init?: boolean;                // Optional: Auto-initialize on creation (default: true)
  user?: PipebackUser;           // Optional: User information
  callbacks?: PipebackCallbacks; // Optional: Event callbacks
  cdnUrl?: string;               // Optional: Custom CDN URL (default: https://widget.pipeback.com/l.js)
}

interface PipebackUser {
  id: string;                    // Required: User ID
  name: string;                  // Required: User name
  email: string;                 // Required: User email
  signature?: string;            // Optional: User verification hash (HMAC-SHA256)
  company?: {
    id: string;                  // Required: Company ID
    name: string;                // Required: Company name
    website?: string;            // Optional: Company website
  };
  attributes?: {                 // Optional: Custom user attributes
    [key: string]: string | number | boolean | null | undefined;
  };
}

interface PipebackCallbacks {
  onLoaded?: () => void;         // Called when widget is loaded
  onOpen?: () => void;           // Called when widget is opened
  onClose?: () => void;          // Called when widget is closed
  onShow?: () => void;           // Called when widget is shown
  onHide?: () => void;           // Called when widget is hidden
}

Methods

init(): Promise<void>

Initialize and load the Pipeback widget. By default, this is called automatically when you create the instance. You only need to call this manually if you set init: false in the config.

// Auto-initialization (default)
const pipeback = Pipeback({ workspaceId: 'xxx' });
// Widget is ready to use!

// Manual initialization (opt-in)
const pipeback = Pipeback({
  workspaceId: 'xxx',
  init: false
});
await pipeback.init();

isReady(): boolean

Check if the widget is ready to use.

if (pipeback.isReady()) {
  pipeback.open();
}

open(): void

Open the widget.

pipeback.open();

close(): void

Close the widget.

pipeback.close();

show(): void

Show the widget (makes it visible).

pipeback.show();

hide(): void

Hide the widget (makes it invisible but keeps it loaded).

pipeback.hide();

navigate(section: string, param?: string): void

Navigate to a specific section of the messenger.

Available sections:

• 'home' - Navigate to home
• 'messages' - Navigate to messages
• 'help' - Navigate to help center
• 'news' - Navigate to product updates
• 'newMessage' - Start a new conversation (optional: prefill text)
• 'helpArticle' - Open help article (requires article UUID)
• 'newsPost' - Open news post (requires post UUID)

// Navigate to home
pipeback.navigate('home');

// Navigate to messages
pipeback.navigate('messages');

// Navigate to help center
pipeback.navigate('help');

// Navigate to product updates
pipeback.navigate('news');

// Start new message with prefilled text
pipeback.navigate('newMessage', 'I need help with billing');

// Open specific help article
pipeback.navigate('helpArticle', 'article-uuid');

// Open specific news post
pipeback.navigate('newsPost', 'post-uuid');

User Attributes

You can pass any custom attributes to track user information:

const pipeback = Pipeback({
  workspaceId: 'YOUR_WORKSPACE_ID',
  user: {
    id: 'user-123',
    name: 'John Doe',
    email: '[email protected]',
    attributes: {
      plan: 'pro',
      monthly_spend: 5000,
      role: 'admin',
      department: 'engineering',
      signup_date: '2024-01-01',
      is_premium: true
    }
  }
});

Security: User Identity Verification

For production environments, you should use the signature field to verify user identity:

const pipeback = Pipeback({
  workspaceId: 'YOUR_WORKSPACE_ID',
  user: {
    id: 'user-123',
    name: 'John Doe',
    email: '[email protected]',
    signature: 'USER_HASH_FROM_BACKEND' // Generate this on your backend
  }
});

The signature should be generated on your backend using HMAC-SHA256 with your Pipeback secret key.

TypeScript Support

This package is written in TypeScript and includes full type definitions.

import Pipeback, { type PipebackInstance } from '@pipeback/pipeback-js';

const pipeback: PipebackInstance = Pipeback({
  workspaceId: 'YOUR_WORKSPACE_ID',
  user: {
    id: 'user-123',
    name: 'John Doe',
    email: '[email protected]'
  }
});

// TypeScript infers all types automatically!
pipeback.open();

License

MIT

Support

• Documentation: https://docs.pipeback.com
• Email: [email protected]
• Website: https://pipeback.com