DEV Community: Ruben

I published an npm SDK for my free WhatsApp API (TypeScript, zero deps)

Ruben — Sun, 05 Jul 2026 14:58:43 +0000

What we just shipped

After the free WhatsApp link API and the Business Platform (BSUID) API, one piece was missing: a ready-to-install client, so you don't have to hand-write fetch calls and error parsing every time you use the API from TypeScript or JavaScript.

It's called whatsusernames-sdk — open source (MIT), zero runtime dependencies, covering all 12 endpoints: the 7 link/QR/validation ones and the 5 Business Platform ones.

Install and use

npm install whatsusernames-sdk

import { createClient } from "whatsusernames-sdk";

const wa = createClient();

const { link, shortLink } = await wa.usernameLink({ username: "joao.silva" });
const qr = await wa.qr({ username: "joao.silva", format: "svg" });
// qr.body is a Uint8Array, qr.contentType is "image/svg+xml"

And for the Business Platform:

const parsed = await wa.business.bsuid.parse({ bsuid: "US.13491208655302741918" });
// { countryCode: "US", id: "13491208655302741918", isParent: false }

const contact = await wa.business.contact.resolve({ username: "joao.silva" });

const normalized = await wa.business.webhook.normalize(rawCloudApiWebhookPayload);

Why an SDK, not just the REST API

The REST API itself is already free and keyless — any fetch call reaches it. The SDK exists for anyone who wants:

Ready-made TypeScript types for all 12 responses (UsernameLinkResult, ResolvedContact, NormalizedWebhook, and more), no hand-written interfaces.
Consistent errors: any non-200 response throws WhatsUsernamesApiError with status, code, and message — one catch covers everything.
Zero dependencies: uses only native fetch, works on Node 18+, browsers, and edge runtimes, without bloating your node_modules.
ESM and CommonJS: import or require(), both work with no extra config.

Self-hosted

Running your own instance (or testing against localhost)? Point the client there:

const wa = createClient({ baseUrl: "http://localhost:3000" });

Open source

The SDK is on GitHub, MIT licensed: github.com/insidedcpulse-spec/whatsusernames-sdk. Issues and PRs welcome — it's the first concrete step toward making WhatsUsernames.link an open platform for developers, not just a closed product.

Full docs at whatsusernames.link/developers and the OpenAPI 3.1 specification.

I added BSUID and business-username support to my free WhatsApp API

Ruben — Sun, 05 Jul 2026 13:05:46 +0000

What we just shipped

After launching the free WhatsApp link API, we expanded to the other side of WhatsApp: the Business Platform / Cloud API. Five new endpoints, all POST with a JSON body, for anyone building integrations, bots, or CRMs on top of Meta's official Cloud API.

This API solves a concrete problem: the Cloud API recently introduced BSUID (Business-Scoped User ID) and business usernames, and both now show up in message and status webhooks — but with no ready-made tooling to validate, parse, or normalize that data. That's the gap we filled.

What a BSUID is

A BSUID is a unique user identifier, built so you can message someone without knowing their phone number. Format: ISO 3166 country code + period + up to 128 alphanumeric characters — for example US.13491208655302741918. Managed accounts with multiple eligible portfolios use a "parent" variant: US.ENT.11815799212886844830.

BSUIDs are scoped to a portfolio: only business phone numbers inside the same portfolio can use a given BSUID. It's opaque — not meant to be split apart for use in requests — but sometimes you need to parse it for debugging, logging, or an internal dashboard. That's what the first two endpoints are for.

The five endpoints

Endpoint	What it does
`POST /api/v1/business/bsuid/validate`	Checks whether a BSUID has the correct format
`POST /api/v1/business/bsuid/parse`	Extracts country code, id, and whether it's a "parent" account
`POST /api/v1/business/username/validate`	Validates the structure of a business username
`POST /api/v1/business/contact/resolve`	Resolves a contact from bsuid, phone, or username — always the same shape
`POST /api/v1/business/webhook/normalize`	Normalizes a raw Cloud API webhook payload into consistent events

Same guarantees as the original API: no API key, no signup, CORS enabled, 60 requests per minute per IP, errors always JSON with a stable code.

Quick examples

Parsing a BSUID:

curl -X POST "https://whatsusernames.link/api/v1/business/bsuid/parse" \
  -H "Content-Type: application/json" \
  -d '{"bsuid": "US.13491208655302741918"}'

Response:

{ "countryCode": "US", "id": "13491208655302741918", "isParent": false }

Resolving a contact from a username (or a phone, or a bsuid — always exactly one of the three):

curl -X POST "https://whatsusernames.link/api/v1/business/contact/resolve" \
  -H "Content-Type: application/json" \
  -d '{"username": "joao.silva"}'

Normalizing a webhook received straight from the Cloud API, without writing your own payload parser:

curl -X POST "https://whatsusernames.link/api/v1/business/webhook/normalize" \
  -H "Content-Type: application/json" \
  -d @webhook-payload.json

Why normalizing webhooks matters

The Cloud API exposes the BSUID and username in slightly different shapes depending on webhook type: incoming messages carry from_user_id and a contacts block; status updates carry recipient_user_id; failures omit the contacts block entirely. The webhook/normalize endpoint absorbs that variation and always returns the same shape — kind, bsuid, phone, username, displayName, raw — so your webhook handler doesn't need to know every case.

Full documentation

All five endpoints are documented at whatsusernames.link/developers, with JSON body examples for each, and in the OpenAPI 3.1 specification — now twelve paths total, including the new schemas (BsuidValidation, BsuidParse, ResolvedContact, NormalizedWebhook, and more).

If you're building on top of the Cloud API and this saves you work, I'd love to hear about it.

I built a free, keyless API for generating WhatsApp links and QR codes

Ruben — Sun, 05 Jul 2026 07:15:29 +0000

I run WhatsUsernames.link, a free WhatsApp link + QR code generator. This week I shipped everything the site does as a public REST API — and made three decisions I wish more small APIs made:

No API key, no signup. Call the endpoint, get the response. No dashboard, no token, no confirmation email.
Free, with per-IP rate limits generous enough for real use.
CORS enabled on every endpoint — call it straight from the browser on a static site, no backend needed.

The endpoints

Base URL: https://whatsusernames.link. Everything is GET.

Endpoint	What it does
`/api/v1/username-link`	WhatsApp link + short link from a username
`/api/v1/phone-link`	Official wa.me link from a phone number
`/api/v1/validate/username`	Validates username structure
`/api/v1/validate/key`	Validates a Username Key (4-8 letters/numbers)
`/api/v1/validate/phone`	Validates an international phone number
`/api/v1/qr`	QR code (PNG or SVG), custom size and colors
`/api/v1/openapi.json`	OpenAPI 3.1 spec of the API itself

Try it right now

curl "https://whatsusernames.link/api/v1/username-link?username=joao.silva"

{
  "username": "joao.silva",
  "link": "https://wa.me/joao.silva",
  "shortLink": "https://whatsusernames.link/joao.silva",
  "notice": "As of 2026-07-04, wa.me/<username> links do not yet open a chat for most accounts..."
}

From the browser, no library:

const res = await fetch(
  "https://whatsusernames.link/api/v1/phone-link?phone=351912345678&text=hello"
);
const { link } = await res.json();
// https://wa.me/351912345678?text=hello

A WhatsApp-green QR code as SVG, ready to drop into an <img> tag:

https://whatsusernames.link/api/v1/qr?username=joao.silva&format=svg&color=25d366

Design decisions that might interest you

Stable error codes. Errors are always JSON with a machine-readable code that never changes within v1:

{
  "error": {
    "code": "username_length",
    "message": "Username must be 3-35 characters."
  }
}

Honest responses about a moving target. WhatsApp's @username feature is in a phased regional rollout, and wa.me/<username> links don't open a chat for most accounts yet (I verified this empirically — server-side redirects and real-device taps). Instead of pretending otherwise, the username-link response includes a notice field with the current status, so your app is never caught off guard. Phone-number links (wa.me/<number>) are officially documented and work for everyone today.

Anti-phishing QR restriction. The QR endpoint only encodes wa.me links built from a validated username or phone number — never arbitrary content. You can't use it to mint QR codes pointing anywhere else.

Rate limiting that fails open. 60 req/min per IP for JSON, 20/min for QR (sliding window via Upstash Redis). Responses carry X-RateLimit-* headers, and 429s include Retry-After. If Redis is ever slow or down, requests proceed — availability over strictness for a free utility API.

Machine-readable spec. The OpenAPI 3.1 document means you can codegen a client — or just point an AI agent at it and it knows how to build WhatsApp links correctly. There's also an llms.txt on the site for the same reason.

What people are building with it

Landing pages that generate contact links dynamically, no backend
CRM/internal tools validating numbers before outreach campaigns
Print-material generators needing brand-colored SVG QR codes
n8n/Zapier/scripts building WhatsApp links on the fly

Docs live at whatsusernames.link/developers. Stack, for the curious: Next.js 15 route handlers on Vercel, Upstash Redis for rate limiting, qrcode for server-side QR generation, all TDD'd with Vitest.

If you build something with it, I'd genuinely love to hear about it in the comments.

wa.me/username doesn't work yet — I verified it two ways

Ruben — Sat, 04 Jul 2026 12:36:04 +0000

`wa.me/username` doesn't work yet — I verified it two ways, here's what to use instead

If you've tried to build a "share my WhatsApp" link using a @username instead of a phone number, you've probably assumed wa.me/username (or wa.me/u/username) works the same way wa.me/15551234567 does. It doesn't — at least not yet, as of writing this.

I wanted a definitive answer instead of trusting blog posts or AI chatbot answers (more on that below), so I tested it two independent ways.

Test 1: server response

curl -I https://wa.me/u/some_real_reserved_username

Every username path I tried — including a certified-real, currently-reserved username — 302-redirects to:

api.whatsapp.com/resolve/?deeplink=...&not_found=1

Compare that to the phone-number path, which redirects to:

api.whatsapp.com/send/?phone=...&type=phone_number

Different resolver, different outcome. The server-side route for usernames exists, but every lookup currently resolves as "not found" — even for real, live usernames.

Test 2: real device

Server response alone doesn't rule out Universal Links / App Links intercepting the URL client-side before it ever hits a server — curl can't see that. So I also opened all three link variants (wa.me/username, wa.me/u/username, and a redirect through my own domain) on a real phone with WhatsApp installed.

None of them opened a chat.

Why this matters if you're building anything around WhatsApp usernames

WhatsApp has rolled out @username handles as a real, user-facing feature — but it hasn't published a public deep-link spec for opening a chat from one, the way it has for phone numbers for years. If you're building a tool, a profile page, a business card generator, anything that assumes wa.me/username "just works," it doesn't, for anyone.

One more data point: I asked Meta AI directly about this, with the counter-evidence above in hand. It kept asserting the link already works and didn't engage with the evidence when pushed. That's a useful reminder that chatbot answers about a fast-moving platform feature can be reciting stale/roadmap content rather than reflecting the live system — verify claims like this yourself before shipping something that depends on them.

What actually works today

Until WhatsApp ships the real format, there are two things that work with zero surprises:

Phone number link — wa.me/<countrycode><number> still opens a chat directly, no manual step, no ambiguity.
Username as a manual lookup — share the @username (plus the "Username Key" if the person set one, which disambiguates people who share a username) as text or a QR code, with an explicit "find me by username" instruction. One extra manual step, but it doesn't expose a phone number.

I built a small free tool that generates both — link + downloadable QR — and is explicit on-page about which one actually works right now instead of pretending the username link is live: whatsusernames.link. No signup, nothing stored server-side.

If anyone finds a case where wa.me/username does resolve for them, I'd genuinely like to know — that would mean a staged rollout is underway.

How I built a free event-sourced world model to stop multiple LLM agents from corrupting shared state

Ruben — Tue, 30 Jun 2026 21:34:49 +0000

The problem

I kept hitting the same wall building multi-agent systems: LLMs that write directly to shared state corrupt it. They hallucinate field values, conflict with each other, produce structurally invalid data. The more agents you add, the worse it gets — corruption compounds.

Every framework I looked at assumed agents could be trusted to write directly. They cannot.

The solution: propose-validate-commit

Agents never write directly. They submit visions — batches of proposed state-mutation ops. A deterministic, non-LLM worker validates every op against entity schemas and consistency rules, then either commits the entire batch atomically or rejects it.

One bad op → entire vision rejected. No partial commits. No corruption.

Agent → POST /api/v1/world/vision → Validator → world_state (PostgreSQL)
                                         ↓
                                   knowledge graph (graph_nodes / graph_edges)

Every accepted event is also projected into a causal knowledge graph in the same transaction — automatically.

What I built

InsideDCPulse is an open-source, production-grade implementation of this pattern, live and free to use.

Stack

FastAPI + PostgreSQL (event store + materialized world_state) + Redis + nginx
Prometheus + Grafana for observability
Self-hostable via docker compose up

What is running live

MCP server — 11 tools at https://insidedcpulse.com/mcp/, registered on MCP Registry and Smithery
7 autonomous LLM agents running on hourly cron, continuously evolving the world state:
- sre-agent (:05) — team/incident management
- threat-intel-agent (:15) — CISA KEV CVE feed
- deploy-agent (:20) — deployments/services
- agent-architect (:30) — A2A protocol proposals from arXiv
- alert-agent (:35) — alerts/regions
- ai-research-agent (:40) — AI systems arXiv papers
- research-agent (:50) — SRE/ops arXiv papers
Per-agent reputation (0–1): drops on rejected proposals, eventually blocks persistent bad actors

The 11 MCP tools

Tool	What it does
`get_world_state`	Current materialized world state
`get_world_memory`	Paginated event audit log
`simulate_action`	Dry-run ops, nothing persisted
`evaluate_vision`	Score a vision against validation rules
`propose_vision`	Queue a vision for validation + commit
`register_agent`	Self-register, get `agent_id` + `api_key`
`get_graph_node`	Knowledge-graph node + all edges
`get_graph_neighbors`	Immediate neighbors by edge type
`find_related_entities`	Shortest path between two nodes
`get_event_timeline`	Chronological event timeline
`get_causal_chain`	Walk CAUSED edges upstream/downstream

Try it right now

No registration needed — shared demo key:

curl -s https://insidedcpulse.com/api/v1/world/state \
  -H "X-API-Key: j9zRmojp8EqBSLaRZwJatcRQa0HwcXK9-sqY70eIxtY"

Or connect via MCP:

{
  "mcpServers": {
    "insidedcpulse": {
      "url": "https://insidedcpulse.com/mcp/"
    }
  }
}

Get your own agent_id + api_key (no approval, no email):

curl -s -X POST https://insidedcpulse.com/api/v1/agents/register-self \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

The causal knowledge graph

Every accepted event automatically creates nodes and edges in a causal knowledge graph — no extra work from agents.

Causal rules (heuristic, with confidence 0–1):

R1: explicit cross-entity references in op values → confidence 1.0
R2: alert-firing events precede incident-open events (recency-weighted)
R3: deployment events precede service degradation events (recency-weighted)

Query it:

# Causal chain from an incident
curl "https://insidedcpulse.com/api/v1/graph/causal-chain?node_id=incident.inc1&direction=upstream" \
  -H "X-API-Key: j9zRmojp8EqBSLaRZwJatcRQa0HwcXK9-sqY70eIxtY"

Entity schemas (validated deterministically)

All keys follow <entity>.<id>.<field>. Current supported types: region, service, incident, deployment, team, alert, research, finding, vulnerability, proposal.

Validation is all-or-nothing: one inconsistent op in a vision rejects the entire batch.

Links

Live: https://insidedcpulse.com
MCP endpoint: https://insidedcpulse.com/mcp/
Interactive API docs: https://insidedcpulse.com/docs
Source (MIT): https://github.com/insidedcpulse-spec/insidedcpulse-world-model
Context for AI systems: https://insidedcpulse.com/llms.txt

Curious if others have hit the same multi-agent corruption problem and what patterns you used. The propose-validate-commit approach feels underexplored compared to just giving agents direct tool access to shared state.

DEV Community: Ruben

I published an npm SDK for my free WhatsApp API (TypeScript, zero deps)

What we just shipped

Install and use

Why an SDK, not just the REST API

Self-hosted

Open source

I added BSUID and business-username support to my free WhatsApp API

What we just shipped

What a BSUID is

The five endpoints

Quick examples

Why normalizing webhooks matters

Full documentation

I built a free, keyless API for generating WhatsApp links and QR codes

The endpoints

Try it right now

Design decisions that might interest you

What people are building with it

wa.me/username doesn't work yet — I verified it two ways

wa.me/username doesn't work yet — I verified it two ways, here's what to use instead

Test 1: server response

Test 2: real device

Why this matters if you're building anything around WhatsApp usernames

What actually works today

How I built a free event-sourced world model to stop multiple LLM agents from corrupting shared state

The problem

The solution: propose-validate-commit

What I built

Stack

What is running live

The 11 MCP tools

Try it right now

The causal knowledge graph

Entity schemas (validated deterministically)

Links

`wa.me/username` doesn't work yet — I verified it two ways, here's what to use instead