@getmesslo/messlo-whatsapp-login

Client-side TypeScript SDK for implementing Messlo Login with WhatsApp in React or Next.js applications.

This package provides:

• a framework-agnostic client (MessloWhatsAppLoginClient)
• a React hook (useMessloWhatsAppLogin)
• a lightweight React reference component (MessloWhatsAppLoginButton)
• a tiny Next.js helper for route base path

Why this package

WhatsApp login is a multi-step flow (start session -> wait for verification -> resolve token).
This package standardizes the flow with strong typing, clear errors, retry handling, and documented integration patterns suitable for production and open-source projects.

Installation

npm install @getmesslo/messlo-whatsapp-login

Live-style demo project in this repository:

• examples/nextjs-whatsapp-login-demo

For backend proxy routes, install Node SDK:

npm install messlo-node-sdk

Peer dependencies:

• react (for /react exports)

Before you write code (Messlo setup)

If you are new, do these steps first inside your Messlo dashboard.

1) Create a Login with WhatsApp app in Messlo

1. Open Messlo dashboard.
2. Go to Developer -> Login with WhatsApp.
3. Click Create app.
4. Select:

• app name
• platform (Web or Flutter)
• WhatsApp phone source (your WABA or Messlo shared number)
• optional login success reply message

5. Save.

After create, Messlo shows credentials. Copy and store them safely.

2) Values you will get from Messlo

From the created app, you will get:

• API Key: used by your backend to call Messlo start/status APIs
• Webhook Secret: used to verify webhook signatures (if you use webhooks)
• Webhook URL(s): endpoint(s) where Messlo can notify your backend
• Login message format: what end user sends on WhatsApp (example shown in Messlo UI)

Important:

• API key and webhook secret are sensitive. Never hardcode in frontend.
• Put them only in backend environment variables or secret manager.

3) Configure your backend env

Typical env example:

MESSLO_WA_LOGIN_API_KEY=your_api_key_here
MESSLO_WA_LOGIN_WEBHOOK_SECRET=your_webhook_secret_here
MESSLO_API_BASE_URL=https://api.messlo.com

4) (Optional) Configure app webhook in Messlo

If you need backend event notifications when login is completed:

1. Add your server webhook URL in the same app (Developer -> Login with WhatsApp -> Edit app), e.g.:
   • https://<your-domain>/api/messlo/webhook
2. Keep the webhook secret from Messlo.
3. Verify signatures on your webhook endpoint before processing payload.

5) Create proxy endpoints in your app (recommended with messlo-node-sdk)

Frontend should never call protected Messlo APIs directly with API key.

Create server-side proxy routes (Next.js API routes, Express routes, etc.) and expose:

• POST /api/auth/whatsapp-login/start
• GET /api/auth/whatsapp-login/status/:sessionId
• GET /api/auth/whatsapp-login/events/:sessionId?token=...

These routes should talk to Messlo using your backend secrets.

You can implement these 3 routes in minutes using messlo-node-sdk adapters (Next/Express) instead of writing low-level proxy logic manually.

Quick end-to-end flow (easy version)

1. User clicks Login with WhatsApp in your UI.
2. Your frontend calls start route.
3. Backend calls Messlo using API key, returns waLink + sessionId + subscribeToken.
4. Frontend shows QR/open-whatsapp link.
5. User sends login message in WhatsApp.
6. Frontend listens on SSE events endpoint.
7. On verified event, frontend fetches status and gets verificationToken.
8. Frontend sends verification token to your auth backend to create app session/JWT.
9. User is logged in.

Expected backend/proxy endpoints

Your app should expose/proxy these endpoints (usually from your own backend or Next.js API routes):

• POST {basePath}/start
• GET {basePath}/status/:sessionId
• GET {basePath}/events/:sessionId?token=... (SSE)

basePath example: /api/auth/whatsapp-login

Recommended backend implementation (with messlo-node-sdk)

Use messlo-node-sdk for these routes instead of hand-writing API proxy logic.

npm install messlo-node-sdk

Next.js App Router example

// lib/messlo.ts
import { MessloNodeSdk } from "messlo-node-sdk";

export const messloSdk = new MessloNodeSdk({
  apiKey: process.env.MESSLO_WA_LOGIN_API_KEY!
});

// app/api/auth/whatsapp-login/start/route.ts
import { nextAdapter } from "messlo-node-sdk";
import { messloSdk } from "@/lib/messlo";

export const POST = nextAdapter.startRoute(messloSdk);

// app/api/auth/whatsapp-login/status/[sessionId]/route.ts
import { nextAdapter } from "messlo-node-sdk";
import { messloSdk } from "@/lib/messlo";

export const GET = nextAdapter.statusRoute(messloSdk);

// app/api/auth/whatsapp-login/events/[sessionId]/route.ts
import { nextAdapter } from "messlo-node-sdk";
import { messloSdk } from "@/lib/messlo";

export const GET = nextAdapter.eventsRoute(messloSdk);

Recommended folder structure (Next.js App Router)

app/api/auth/whatsapp-login/start/route.ts
app/api/auth/whatsapp-login/status/[sessionId]/route.ts
app/api/auth/whatsapp-login/events/[sessionId]/route.ts

Express example

import express from "express";
import { MessloNodeSdk, expressAdapter } from "messlo-node-sdk";

const router = express.Router();
const sdk = new MessloNodeSdk({
  apiKey: process.env.MESSLO_WA_LOGIN_API_KEY!
});

router.post("/api/auth/whatsapp-login/start", expressAdapter.startRoute(sdk));
router.get("/api/auth/whatsapp-login/status/:sessionId", expressAdapter.statusRoute(sdk));
router.get("/api/auth/whatsapp-login/events/:sessionId", expressAdapter.eventsRoute(sdk));

What beginners usually miss

• Using API key in frontend bundle (never do this).
• Not regenerating QR/message after error or expired session.
• Not validating webhook signature.
• Not handling role/account-not-found cases in login flow.
• Reusing stale sessionId/subscribeToken after a failed attempt.

Core client usage (framework-agnostic)

import { MessloWhatsAppLoginClient } from "@getmesslo/messlo-whatsapp-login";

const client = new MessloWhatsAppLoginClient({
  basePath: "/api/auth/whatsapp-login"
});

const session = await client.startSession();
// show session.waLink as QR / deep link to user

const verificationToken = await client.waitForVerification(
  session.sessionId,
  session.subscribeToken
);

// send verificationToken to your backend to create app session

React hook usage

import { useMessloWhatsAppLogin } from "@getmesslo/messlo-whatsapp-login/react";

function LoginWithWhatsApp() {
  const wa = useMessloWhatsAppLogin({
    basePath: "/api/auth/whatsapp-login",
    onVerified: async (verificationToken) => {
      await fetch("/api/auth/finalize-wa-login", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ verificationToken })
      });
      window.location.href = "/dashboard";
    }
  });

  return (
    <div>
      <button onClick={() => void wa.start()} disabled={wa.isStarting || wa.isWaiting}>
        {wa.isStarting ? "Preparing..." : "Login with WhatsApp"}
      </button>

      {wa.session?.waLink ? (
        <a href={wa.session.waLink} target="_blank" rel="noreferrer">
          Open WhatsApp
        </a>
      ) : null}

      {wa.error ? (
        <div>
          <p>{wa.error}</p>
          <button onClick={() => void wa.retry()}>Generate new QR/message</button>
        </div>
      ) : null}
    </div>
  );
}

React button component with display options

MessloWhatsAppLoginButton supports session presentation mode:

• displayMode="link": open WhatsApp link only (default)
• displayMode="qr": QR code only
• displayMode="both": show both QR + link

import { MessloWhatsAppLoginButton } from "@getmesslo/messlo-whatsapp-login/react";

<MessloWhatsAppLoginButton
  basePath="/api/auth/whatsapp-login"
  displayMode="both"
  onVerified={async (verificationToken) => {
    await fetch("/api/auth/finalize-wa-login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ verificationToken })
    });
  }}
/>;

QR helper for custom UIs

If you use the hook and a custom UI, generate QR URL from waLink:

import { getWhatsAppQrCodeUrl } from "@getmesslo/messlo-whatsapp-login";

const qrUrl = getWhatsAppQrCodeUrl(session.waLink, 280);

Next.js helper

import { createNextWhatsAppLoginBasePath } from "@getmesslo/messlo-whatsapp-login/next";

const basePath = createNextWhatsAppLoginBasePath("/api/auth/whatsapp-login");
// "/api/auth/whatsapp-login"

Error handling and retries

• Any terminal error should create a fresh session (new QR/message) before retrying.
• Do not keep reusing stale sessions after failed sign-in or expired events.
• Surface user-friendly fallback actions such as:
  • "Generate new QR"
  • "Try again"

Public API

MessloWhatsAppLoginClient

• startSession(): Promise<StartSessionResponse>
• getStatus(sessionId: string): Promise<StatusResponse>
• waitForVerification(sessionId: string, subscribeToken: string, options?): Promise<string>

useMessloWhatsAppLogin

Returns:

• session
• isStarting
• isWaiting
• error
• start()
• retry()
• reset()

Package development

npm install
npm run build
npm run typecheck

Versioning and stability

• Current status: 0.x (early)
• Breaking changes may happen between minor versions until 1.0.0

License

MIT