npm package: @snugdesk/whatsapp-widget
Description: WhatsApp widget for Angular Apps - Powered by Snugdesk
Latest version: 0.2.27

# 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**  
📧 [sales@snug.in](mailto:sales@snug.in)

---

## ✅ 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.

```bash
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:

1. **Create `src/custom-polyfills.ts`**

   ```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.

2. **Register the polyfill file in `angular.json`**

   ```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"
               ]
             }
           }
         }
       }
     }
   }
   ```

3. **Let TypeScript know about the polyfill file**

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

   ```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`)

```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

```ts
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).

```ts
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';
}
```

```html
<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.

```html
<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:

```json
{
  "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**  
📧 [support@snug.in](mailto:support@snug.in)

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

---