whatsapp-activity

A lightweight and robust npm package to parse WhatsApp Business API webhook payloads and format them into human-readable activity strings (e.g. status updates or incoming messages) with flexible recipient/sender masking.

Built for compatibility, it supports older Node.js versions (Node.js >= 4.0.0) by utilizing CommonJS exports and zero modern syntax dependencies.

Features

• Class-based API: Configure parser options once and reuse the instance.
• Robust Parsing: Safe payload traversal powered by lodash.get prevents runtime property access errors.
• Recipient/Sender Masking: Mask phone numbers (e.g. 9177777777777 becomes 917………777) with configurable characters and lengths.
• Incoming and Outgoing Activity: Parses both incoming customer messages and outgoing message status updates (sent, delivered, read, failed).

Installation

npm install whatsapp-activity

Usage

Simple Example

const WhatsappActivity = require('whatsapp-activity');

// Initialize with default configuration (masking enabled)
const parser = new WhatsappActivity();

const payload = {
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "4299968420315031",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "916666666666",
              "phone_number_id": "6666666666464"
            },
            "statuses": [
              {
                "recipient_id": "9177777777777",
                "status": "sent"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
};

const activity = parser.toEnglish(payload);
console.log(activity);
// Output: "Message sent to 917………777 from business number 916666666666"

Unmasked Output

To disable masking and show full phone numbers:

const parser = new WhatsappActivity({ mask: false });

const activity = parser.toEnglish(payload);
console.log(activity);
// Output: "Message sent to 9177777777777 from business number 916666666666"

Custom Mask Configuration

You can customize the masking character and length:

const parser = new WhatsappActivity({
  mask: true,
  maskChar: '*',
  maskLength: 5
});

const activity = parser.toEnglish(payload);
console.log(activity);
// Output: "Message sent to 917***777 from business number 916666666666" (using 3 is default, but here 5 asterisks will be used: 917*****777)

Options Configuration

When creating a new instance: new WhatsappActivity(options)

| Option | Type | Default | Description | |---|---|---|---| | mask | boolean | true | When true, hides the middle characters of the recipient/sender phone number. | | maskChar | string | '…' | The character or string used as the mask. | | maskLength | number | 3 | How many times maskChar is repeated. |