@snugdesk/whatsapp-widget

Snugdesk - WhatsApp Widget for Angular

A production-ready Angular library that embeds the full Snugdesk WhatsApp agent experience inside your web application. The widget handles authentication, conversation management, message templates, media uploads, emoji reactions, and rich UI states out of the box.

To purchase licenses or to get implementation assistance, reach out to:

SNUG Technologies Pvt Ltd
📧 [e-mail]

✅ Requirements

• Angular 19.0.0+ (matches the published peer dependency range)
• A licensed Snugdesk tenant with access to the WhatsApp channel

📦 Installation

Install the core runtime first (all Snugdesk widgets depend on it), then add the WhatsApp widget.

npm install @snugdesk/core
npm install @snugdesk/whatsapp-widget

Other runtime dependencies are bundled (@aws-sdk/client-s3, @ctrl/ngx-emoji-mart, ngx-avatars, ngx-infinite-scroll, ngx-skeleton-loader, moment-timezone, libphonenumber-js, sort-nested-json, uuid, …).

🛠 Workspace Configuration (required)

The AWS SDK for JavaScript (v3) expects Node-style globals (global, process) to exist. Add the following once in your host application:

• Create src/custom-polyfills.ts

  // src/custom-polyfills.ts
  (window as any).global = window;
  (window as any).process = { env: { DEBUG: undefined } };
  

  Keep additional polyfills above if your app already uses this file.

• Register the polyfill file in angular.json

  {
    "projects": {
      "your-app": {
        "architect": {
          "build": {
            "options": {
              "polyfills": [
                "zone.js",
                "src/custom-polyfills.ts"
              ]
            }
          },
          "test": {
            "options": {
              "polyfills": [
                "zone.js",
                "zone.js/testing",
                "src/custom-polyfills.ts"
              ]
            }
          }
        }
      }
    }
  }
  

• Let TypeScript know about the polyfill file

  Add the file to the files array in both tsconfig.app.json and tsconfig.spec.json:

  {
    "files": [
      "src/custom-polyfills.ts"
    ]
  }
  

These changes ensure the widget (and its client libraries) run reliably in both builds and tests.

⚙️ Angular Setup

Standalone bootstrap (main.ts)

import { bootstrapApplication } from '@angular/platform-browser';
import { provideAnimations } from '@angular/platform-browser/animations';
import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideAnimations(),
    provideHttpClient(withInterceptorsFromDi()),
  ]
});

NgModule-based apps

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { HttpClientModule } from '@angular/common/http';
import { WhatsAppWidgetModule } from '@snugdesk/whatsapp-widget';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, HttpClientModule, WhatsAppWidgetModule],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {}

🔐 Authentication Workflow

The widget uses SnugdeskAuthenticationService from @snugdesk/core to exchange the token you supply for a session. Before rendering the component, fetch a short-lived Snugdesk token for the agent (JWT).

import { Component } from '@angular/core';

@Component({
  selector: 'my-component',
  templateUrl: './my-component.html'
})
export class ConversationShellComponent {
  tenantId = 'auth-tenant-id';
  userId = 'auth-user-id';
  token = 'token-issued-by-snugdesk-backend';
  themeColor = '#0f8b5f';
}

<snugdesk-whatsapp-widget
  [tenantId]="tenantId"
  [userId]="userId"
  [token]="token"
  [baseColor]="themeColor">
</snugdesk-whatsapp-widget>

Inputs

• tenantId (required) – Snugdesk tenant identifier for the session.
• userId (required) – Agent/user identifier.
• token (required) – Snugdesk-issued auth token; the widget calls authenticate(...) internally.
• baseColor (optional) – Overrides the primary accent colour used across the UI.

Ensure you render the widget only after you have a fresh token to avoid the component throwing an authentication error.

🧭 Widget Modes

The widget supports two modes: Embedded and Standalone. Use the mode input to choose how the UI behaves.

Embedded mode

• Set mode="Embedded" when you want to embed the widget inside an existing conversation context.
• entityConversation is required in this mode to load the selected conversation.

Standalone mode

• Set mode="Standalone" to run the widget as a full client for the WhatsApp Business API.
• Only token is required for authentication; entityConversation is not required.

<snugdesk-whatsapp-widget
  [token]="sessionToken"
  [mode]="'Standalone'">
</snugdesk-whatsapp-widget>

🎨 Assets & Styling

The library bundles icons, background artwork, and shared CSS under @snugdesk/whatsapp-widget/assets. To make them available during your build, add the folder to the Angular CLI asset list:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "assets": [
              "src/favicon.ico",
              "src/assets",
              {
                "glob": "**/*",
                "input": "./node_modules/@snugdesk/whatsapp-widget/assets",
                "output": "assets/snugdesk-whatsapp"
              }
            ],
            "styles": [
              "src/styles.css",
              "node_modules/@ctrl/ngx-emoji-mart/picker.css"
            ]
          }
        }
      }
    }
  }
}

If you already use custom asset pipelines, copy the contents of node_modules/@snugdesk/whatsapp-widget/assets into a location your app serves at runtime and keep the relative directory structure.

✨ Feature Highlights

• Omni-channel agent console for WhatsApp conversations, contacts, and templates
• Real-time thread updates with infinite-scroll history, skeleton states, and unread indicators
• Message template browsing, preview, and quick actions
• Emoji picker, phone-number parsing, timezone-aware message timelines, and avatar rendering

🛠 Troubleshooting & Tips

• When adjusting the asset output path, make sure the relative URLs in the generated CSS still resolve (keep /assets/snugdesk-whatsapp/... in the final build).
• Upgrade the widget in lockstep with your Angular major version to stay within the supported peer dependency range (>=19.0.0).

📬 Support

Need help with deployment, theming, or backend setup?

SNUG Technologies Pvt Ltd
📧 [e-mail]

Include your tenant name, Angular version, and a summary of the issue so the support team can assist quickly.