whatsapp-compose

Build WhatsApp wa.me links with prefilled message text and an optional recipient phone number.

This package does one thing: it returns a WhatsApp URL string. You can use that URL in browser apps, React or Next.js event handlers, or anywhere else you need to generate a WhatsApp deep link.

Installation

npm install @boris93/whatsapp-compose

API

composeWhatsappMessage(options)

Builds a WhatsApp deep link with prefilled text and an optional recipient phone number.

import { composeWhatsappMessage } from "@boris93/whatsapp-compose";

const url = composeWhatsappMessage({
  text: "Hello from my app",
  phoneNumber: "+491701234567",
});

Parameters

type WhatsappComposeOptions = {
  text: string;
  phoneNumber?: string;
};

• text: The message to prefill in WhatsApp. It is URL-encoded automatically.
• phoneNumber: Optional recipient phone number in international format. Non-digit characters such as +, spaces, dashes, and parentheses are stripped before the URL is built.

Returns

Returns a string WhatsApp URL in one of these forms:

• https://wa.me/?text=...
• https://wa.me/<phone>?text=...

Throws

• Throws an error if phoneNumber is provided but does not contain any digits after normalization.

The function does not open WhatsApp, navigate the browser, or send a message. It only returns the URL.

Usage Examples

Prefill a message without a phone number

import { composeWhatsappMessage } from "@boris93/whatsapp-compose";

const url = composeWhatsappMessage({
  text: "Hello there",
});

// https://wa.me/?text=Hello%20there

Prefill a message for a specific recipient

import { composeWhatsappMessage } from "@boris93/whatsapp-compose";

const url = composeWhatsappMessage({
  text: "Can we talk later?",
  phoneNumber: "+49 170 123 4567",
});

// https://wa.me/491701234567?text=Can%20we%20talk%20later%3F

Open WhatsApp in the browser

import { composeWhatsappMessage } from "@boris93/whatsapp-compose";

try {
  const url = composeWhatsappMessage({
    text: "Hello from the browser",
    phoneNumber: "+491701234567",
  });

  window.open(url, "_blank", "noopener,noreferrer");
} catch (error) {
  console.error("Could not create WhatsApp link", error);
}

Use inside a Next.js or React click handler

import { composeWhatsappMessage } from "@boris93/whatsapp-compose";

export function ContactButton() {
  const handleClick = () => {
    try {
      const url = composeWhatsappMessage({
        text: "Hi, I want to learn more about your service.",
        phoneNumber: "+491701234567",
      });

      window.location.href = url;
    } catch (error) {
      console.error("Invalid WhatsApp link options", error);
    }
  };

  return <button onClick={handleClick}>Chat on WhatsApp</button>;
}

Handle invalid phone numbers

import { composeWhatsappMessage } from "@boris93/whatsapp-compose";

try {
  const url = composeWhatsappMessage({
    text: "Hello",
    phoneNumber: "invalid-number",
  });

  console.log(url);
} catch (error) {
  console.error("Please provide a valid international phone number", error);
}

Notes

• phoneNumber should include the country code.
• The function only builds a WhatsApp URL string. It does not send messages or open WhatsApp by itself.
• If you need to validate phone numbers beyond basic digit extraction, do that before calling the function.