WhatsApp

Lightweight, dependency-free, in-memory WhatsApp Cloud API fake for testing code that talks to the Meta Graph API with axios.

Default port: 4657

It speaks the exact wire protocol an axios-based WhatsApp Cloud API integration uses: Bearer-token auth (Authorization: Bearer <ACCESS_TOKEN>), JSON request bodies (and multipart/form-data for media upload), and JSON responses with the Cloud API envelopes ({ messaging_product, contacts, messages } for sends, { id } for uploads, Graph-style { error: { … } } on failure). Everything sent is captured in memory for assertions and can be reset. Zero cost, zero side effects.

The Graph version prefix (e.g. v21.0) in the path is accepted but optional — /{version}/{id}/... and /{id}/... both route the same way.

Implemented Operations

Send messages (POST /{PHONE_NUMBER_ID}/messages)

A single endpoint that dispatches on the type field. Always requires messaging_product: "whatsapp". On success returns 200 with { messaging_product, contacts: [{ input, wa_id }], messages: [{ id: "wamid.…", message_status: "accepted" }] }.

• type: "text" — text.body required. Supports preview_url and reply context.message_id.
• type: "template" — template.name + template.language.code required; the template must exist (seeded hello_world) and supports components.
• type: "image" | "audio" | "video" | "document" | "sticker" — the media object requires either id (uploaded media) or link.
• type: "location" — requires location.latitude and location.longitude.
• type: "contacts" — requires a non-empty contacts array.
• type: "interactive" — requires interactive.type (e.g. button, list, cta_url).
• type: "reaction" — requires reaction.message_id (and emoji).

Mark as read & typing (POST /{PHONE_NUMBER_ID}/messages)

• { status: "read", message_id } — marks an inbound message read; returns { success: true }.
• Add typing_indicator: { type: "text" } to also emit a typing indicator.

Media

• POST /{PHONE_NUMBER_ID}/media — upload media (multipart messaging_product + type + file, or JSON). Returns { id }.
• GET /{MEDIA_ID} — retrieve media metadata: { messaging_product, url, mime_type, sha256, file_size, id }. The url points at the local /__media/{id} download route.
• DELETE /{MEDIA_ID} — delete uploaded media ({ success: true }).
• GET /__media/{MEDIA_ID} — download the raw bytes (requires the Bearer token), mirroring Cloud API media downloads.

Phone number & WhatsApp Business Account

• GET /{PHONE_NUMBER_ID} — phone number info (display_phone_number, verified_name, quality_rating, code_verification_status, …). Supports ?fields= projection.
• GET /{WABA_ID}/phone_numbers — list phone numbers on the WABA ({ data, paging }).
• GET /{WABA_ID} — WABA info (name, currency, timezone_id, account_review_status, …). Supports ?fields=.

Business profile

• GET /{PHONE_NUMBER_ID}/whatsapp_business_profile — get the profile ({ data: [ { messaging_product, about, address, … } ] }). Supports ?fields=.
• POST /{PHONE_NUMBER_ID}/whatsapp_business_profile — update editable fields (about, address, description, email, profile_picture_url, websites, vertical). Requires messaging_product.

Message templates (management)

• GET /{WABA_ID}/message_templates — list templates ({ data, paging }). Seeded with hello_world (APPROVED).
• POST /{WABA_ID}/message_templates — create a template (name, category, language required); returns { id, status: "PENDING", category }.
• DELETE /{WABA_ID}/message_templates?name=… — delete a template by name ({ success: true }).

Registration & verification

• POST /{PHONE_NUMBER_ID}/register — register a number with a 6-digit pin.
• POST /{PHONE_NUMBER_ID}/deregister — deregister the number.
• POST /{PHONE_NUMBER_ID}/request_code — request a verification code (code_method ∈ SMS|VOICE).
• POST /{PHONE_NUMBER_ID}/verify_code — verify the code (deterministic test code is 123456). Must follow request_code.

Webhook verification

• GET /{any-path}?hub.mode=subscribe&hub.verify_token=…&hub.challenge=… — Meta-style verification handshake. Echoes hub.challenge as text/plain 200 when the token matches WHATSAPP_VERIFY_TOKEN, else 403.

Service & inspection operations (parlel-only, not part of the Cloud API)

• GET / — service metadata.
• GET /health — { "status": "ok" }.
• OPTIONS * — 204 (CORS preflight).
• POST /__parlel/reset — clear all ephemeral state and re-seed defaults.
• GET /__parlel/messages — every captured outbound message ({ messages, count }).
• GET /__parlel/read-receipts — captured read receipts.
• GET /__parlel/typing — captured typing indicators.
• GET /__parlel/media — uploaded media metadata (without raw bytes).
• GET /__parlel/templates — current templates.
• POST /__parlel/inbound — build & queue an inbound message webhook event ({ from, text, name }); returns the Meta webhook payload.
• POST /__parlel/status — build & queue a message-status webhook event ({ message_id, status, recipient_id }).
• GET /__parlel/inbound — list queued webhook events.

Quick Start

import { WhatsappServer } from "./services/whatsapp/src/server.js";
import axios from "axios";

const server = new WhatsappServer(4657);
await server.start();

const ACCESS_TOKEN = "parlel-test-access-token";
const PHONE_NUMBER_ID = "100000000000001";

const wa = axios.create({
  baseURL: "http://127.0.0.1:4657/v21.0",
  headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
});

// Send a text message
const { data } = await wa.post(`/${PHONE_NUMBER_ID}/messages`, {
  messaging_product: "whatsapp",
  recipient_type: "individual",
  to: "15551230000",
  type: "text",
  text: { body: "Hello from parlel!" },
});
console.log(data.messages[0].id); // "wamid.…"

// Send an approved template
await wa.post(`/${PHONE_NUMBER_ID}/messages`, {
  messaging_product: "whatsapp",
  to: "15551230000",
  type: "template",
  template: { name: "hello_world", language: { code: "en_US" } },
});

await server.stop();

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error Codes / Shapes

Failures use the Graph API error envelope:

{
  "error": {
    "message": "(#100) The parameter to is required.",
    "type": "GraphMethodException",
    "code": 100,
    "error_subcode": 33,
    "fbtrace_id": "…",
    "error_data": { "messaging_product": "whatsapp", "details": "to is required" }
  }
}

Environment Variables

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

WHATSAPP_ACCESS_TOKEN=parlel-test-access-token
WHATSAPP_PHONE_NUMBER_ID=100000000000001
WHATSAPP_BUSINESS_ACCOUNT_ID=200000000000001
WHATSAPP_API_VERSION=v21.0
WHATSAPP_VERIFY_TOKEN=parlel-verify-token
WHATSAPP_BASE_URL=http://parlel-bridge:4657