API Gratuita de Links do WhatsApp para Programadores

Gere links do WhatsApp, valide usernames e números de telefone e crie códigos QR com simples pedidos HTTP GET. Sem chave de API, sem registo, grátis. Todos os endpoints devolvem JSON (o endpoint QR devolve uma imagem), enviam cabeçalhos CORS e podem ser chamados diretamente do browser.

Endpoints

URL base: https://whatsusernames.link. Todos os endpoints são GET.

GET /api/v1/username-link?username=joao.silva&key=AB12&text=hello

Link do WhatsApp + link curto a partir de um username (key e texto pré-preenchido opcionais).

GET /api/v1/phone-link?phone=351912345678&text=hello

Link oficial wa.me click-to-chat a partir de um número de telefone internacional.

GET /api/v1/validate/username?username=joao.silva

Verifica se um username é estruturalmente válido.

GET /api/v1/validate/key?key=AB12

Verifica se uma Username Key é válida (4-8 letras/números).

GET /api/v1/validate/phone?phone=351912345678

Verifica se um número de telefone é válido para links do WhatsApp.

GET /api/v1/qr?username=joao.silva&format=svg&color=25d366

Código QR (PNG ou SVG) para um link de username ou telefone. Tamanho e cores personalizáveis.

GET /api/v1/openapi.json

Descrição OpenAPI 3.1 desta API, legível por máquinas.

API da Business Platform

URL base: https://whatsusernames.link. Estes endpoints são POST com corpo JSON, para a WhatsApp Business Platform / Cloud API (BSUID, usernames de negócio, resolução de contactos, normalização de webhooks). Mesmo CORS, limites de utilização e formato de erro dos endpoints acima.

POST /api/v1/business/bsuid/validate

Corpo

{ "bsuid": "US.13491208655302741918" }

Verifica se um Business-Scoped User ID (BSUID) é estruturalmente válido.

POST /api/v1/business/bsuid/parse

Corpo

{ "bsuid": "US.ENT.11815799212886844830" }

Faz parse de um BSUID: código de país, id e flag de conta-mãe (parent).

POST /api/v1/business/username/validate

Corpo

{ "username": "joao.silva" }

Verifica se um username da WhatsApp Business Platform é estruturalmente válido.

POST /api/v1/business/contact/resolve

Corpo

{ "username": "joao.silva" }

Resolve um contacto a partir de exatamente um de bsuid, phone ou username, num formato unificado.

POST /api/v1/business/webhook/normalize

Corpo

{ "entry": [{ "changes": [{ "value": { "messages": [...], "contacts": [...] } }] }] }

Normaliza um payload de webhook bruto da WhatsApp Cloud API (mensagens ou status) num formato de evento consistente.

Exemplos

curl

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

JavaScript (fetch)

const res = await fetch(
  "https://whatsusernames.link/api/v1/username-link?username=joao.silva"
);
const data = await res.json();
console.log(data.link); // https://wa.me/joao.silva

curl (API da Business Platform)

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

Limites de utilização

60 pedidos por minuto por IP nos endpoints JSON, 20 por minuto no endpoint QR. As respostas incluem os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; exceder o limite devolve HTTP 429 com cabeçalho Retry-After. Pedidos idênticos são servidos da cache CDN e não contam para o limite.

Erros

Os erros são sempre JSON com um código estável legível por máquinas: por exemplo, um username inválido devolve HTTP 400 com um corpo como o abaixo. Os códigos nunca mudam dentro da v1.

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

Sobre links wa.me de username

A funcionalidade de usernames do WhatsApp está em rollout regional faseado, e os links wa.me/<username> podem ainda não abrir conversa para todas as contas. O endpoint username-link inclui um campo notice com o estado atual. Os links por número de telefone (wa.me/<telefone>) são oficialmente documentados e funcionam para todos hoje.

Especificação OpenAPI 3.1
API Gratuita de Links do WhatsApp para Programadores