WhatsApp Magic Link

🚫 CAUTION — Never call /magic-link/init from the browser

Your oa_live_xxx API key would be visible in the browser Network tab and could be stolen.

Correct pattern: Frontend calls your own backend (e.g. POST /api/auth/whatsapp/init) → your backend calls EmacronAI CRM with the API key → forwards only session_id, wa_link, scan_url, expires_at to the frontend.

If your backend returns 502 on /init, verify that Authorization: Bearer oa_live_xxx is being sent and the key is valid in Settings → API Keys.

🚫 Call /init from your backend — not from React/Vue/mobile

Exposing your API key in frontend code lets anyone read it from the browser Network tab. See the Authentication section above for the correct architecture.

# 1. Init a session (call from YOUR backend — never from the browser)
curl -X POST https://api.crm.emacronai.com/api/v1/whatsapp/magic-link/init \\
  -H "Authorization: Bearer oa_live_xxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "context": "login",
    "redirect_url": "https://yourapp.com/auth/callback"
  }'

# Response:
{
  "session_id":   "550e8400-e29b-41d4-a716-446655440000",
  "wa_link":      "https://wa.me/919272117887?text=Verify%E2%80%8D...",
  "scan_url":     "https://api.crm.emacronai.com/api/v1/whatsapp/magic-link/UUID/scan",
  "qr_link":      "https://wa.me/919272117887?text=login+3f9a8b2c",
  "message_text": "Verify my login to Acme",
  "redirect_url": "https://yourapp.com/auth/callback",
  "expires_in":   300,
  "expires_at":   "2026-09-04T07:00:00Z"
}

📞 Phone number format — important

The phone field is always returned in strict E.164 format with no spaces, dashes, or parentheses — e.g. +917840985216. If your database stores numbers with spaces or formatting, a direct string comparison will silently return 0 rows. Always normalize both sides before comparing:

# 2. Poll status every 2-3 seconds
curl https://api.crm.emacronai.com/api/v1/whatsapp/magic-link/UUID/status \\
  -H "Authorization: Bearer oa_live_xxx"

# Before verification:
{ "verified": false, "expires_at": "2026-09-04T07:00:00Z" }

# After user sends the WhatsApp message:
{
  "verified":     true,
  "phone":        "+919876543210",
  "verified_at":  "2026-09-04T06:58:23Z",
  "context":      "login",
  "redirect_url": "https://yourapp.com/auth/callback"
}

import { QRCodeSVG } from 'qrcode.react';
import { useState, useEffect } from 'react';

function WhatsAppLoginWidget({ wa_link, scan_url }) {
  const [isMobile, setIsMobile] = useState(false);

  useEffect(() => {
    setIsMobile(/Android|iPhone|iPad|Mobile/i.test(navigator.userAgent));
  }, []);

  return (
    <div>
      {isMobile ? (
        // Mobile: tap button opens WhatsApp directly
        <a href={wa_link} target="_blank" rel="noopener noreferrer">
          Continue with WhatsApp
        </a>
      ) : (
        // Desktop: QR code (use scan_url — it's short and scans cleanly)
        <div>
          <QRCodeSVG value={scan_url} size={200} />
          <p>Scan with your phone camera to verify</p>
        </div>
      )}
    </div>
  );
}

⚠️ React gotcha — countdown initialization causes instant false expiry

When state transitions to "pending", there is a render cycle where your countdown hasn't initialized yet and still reads 0. If you use secondsLeft === 0 as the expiry trigger, the handler fires instantly on the first render — showing “session expired” before the user even sees the QR code.

# Customize the WhatsApp reply message after verification
curl -X PUT https://api.crm.emacronai.com/api/v1/whatsapp/magic-link-config \\
  -H "Authorization: Bearer oa_live_xxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "success_reply":         "You are verified! Returning you to the app...",
    "include_fallback_link": false
  }'

# include_fallback_link:
#   true  (default) — appends "Didn't update? Tap: <link>" to the WA reply
#   false           — sends only your success_reply text, no link appended
#                     Use this for server-side flows where you handle redirect

{
  "type": "magic_link.verified",
  "workspace_id": "ws_xxx",
  "data": {
    "session_id":   "550e8400-e29b-41d4-a716-446655440000",
    "phone":        "+919876543210",
    "context":      "login",
    "redirect_url": "https://yourapp.com/auth/callback",
    "verified_at":  "2026-09-04T06:58:23Z"
  }
}

import { createClient } from '@emacrontechnologies/outreachagent';

const oa = createClient(process.env.OUTREACHAGENT_API_KEY!);

// Step 1: Backend — init session
app.post('/auth/whatsapp/init', async (req, res) => {
  const { session_id, wa_link, scan_url, expires_at } =
    await oa.magicLink.init({
      context:      'login',
      redirect_url: 'https://yourapp.com/auth/callback',
    });
  res.json({ session_id, wa_link, scan_url, expires_at });
});

// Step 2: Backend — poll / handle status
app.get('/auth/whatsapp/status/:id', async (req, res) => {
  const result = await oa.magicLink.status(req.params.id);
  if (result.verified) {
    const jwt = issueJwt(result.phone!);
    // Redirect user back to their app with JWT
    if (result.redirect_url) {
      return res.redirect(result.redirect_url + '?token=' + jwt);
    }
    return res.json({ verified: true, token: jwt, phone: result.phone });
  }
  res.json({ verified: false, expires_at: result.expires_at });
});

See also