A forma prática de "criar" uma API de WhatsApp não é construí-la do zero — é integrar uma API pronta que já resolve a conexão com o WhatsApp. Com a api-wa.me, você cria uma instância, conecta seu número por QR Code e passa a enviar e receber mensagens por simples requisições HTTP, em Node.js, PHP ou qualquer linguagem.

Neste tutorial você vai: (1) entender o conceito de instância e key, (2) conectar o número e (3) enviar sua primeira mensagem em três linguagens.

Antes de começar

Você vai precisar de:

• Uma conta na api-wa.me e a sua key de instância (ela identifica sua conexão e vai na URL).
• Um número de WhatsApp para conectar.
• A base URL da API: https://us.api-wa.me.

A autenticação é simples: a key da instância já vai na própria URL, no formato https://us.api-wa.me/SUA_KEY/.... Não é preciso header de autenticação.

Passo 1 — Conectar o número (QR Code)

Primeiro, solicite a conexão. A API retorna um QR Code que você escaneia no app do WhatsApp em Aparelhos conectados:

curl -X POST "https://us.api-wa.me/SUA_KEY/instance"

Para checar o status da conexão a qualquer momento:

curl "https://us.api-wa.me/SUA_KEY/instance"

Quando o status indicar conectado, você está pronto para enviar mensagens.

Passo 2 — Enviar a primeira mensagem

O endpoint é POST /{key}/message/text, com um corpo JSON contendo o destinatário (to, em formato internacional, só dígitos) e o text.

Com cURL

curl -X POST "https://us.api-wa.me/SUA_KEY/message/text" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5566996852025",
    "text": "Olá! Esta é minha primeira mensagem pela API."
  }'

Com Node.js (SDK oficial)

Instale o SDK:

npm i @raphaelvserafim/client-api-whatsapp

E envie:

import { WhatsApp, TypeMessage } from "@raphaelvserafim/client-api-whatsapp";

const wa = new WhatsApp({
  server: "https://us.api-wa.me",
  key: "SUA_KEY",
});

// Conectar (retorna status e QR Code na primeira vez)
await wa.instance.connect();

// Enviar texto
await wa.message.send(
  {
    type: TypeMessage.TEXT,
    body: { to: "5566996852025", text: "Olá pela API com Node.js!" },
  },
  false
);

Com PHP

Usando o cURL nativo do PHP (funciona em qualquer projeto):

<?php
$key = "SUA_KEY";
$payload = json_encode([
  "to"   => "5566996852025",
  "text" => "Olá pela API com PHP!",
]);

$ch = curl_init("https://us.api-wa.me/$key/message/text");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS     => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;

Prefere um SDK em PHP? Há um cliente oficial em PHP no GitHub.

Passo 3 — Receber mensagens (webhook)

Para reagir a mensagens recebidas, configure um webhook: a API envia um POST para a sua URL sempre que algo acontece. Configure assim:

curl -X PUT "https://us.api-wa.me/SUA_KEY/instance" \
  -H "Content-Type: application/json" \
  -d '{
    "allowWebhook": true,
    "allowNumber": "all",
    "webhookMessage": "https://seu-site.com/webhook"
  }'

Próximos passos

Você já tem o essencial: conectar e enviar. A partir daqui, explore:

• Como enviar mensagens, botões, imagens e listas — recursos avançados;
• A documentação completa da API — todos os endpoints;
• API não oficial do WhatsApp: é segura? — boas práticas para evitar bloqueio.

Perguntas frequentes

Como criar uma API de WhatsApp do zero?+

Em vez de construir uma do zero (o que exige engenharia reversa do protocolo do WhatsApp), o caminho prático é usar uma API pronta como a api-wa.me: você cria uma instância, conecta seu número por QR Code e passa a enviar e receber mensagens por requisições HTTP em qualquer linguagem.

Como integrar o WhatsApp com PHP?+

Faça uma requisição POST para o endpoint /{key}/message/text com o corpo JSON contendo 'to' e 'text'. Você pode usar cURL nativo do PHP ou o SDK PHP oficial (client-php-api-wa-me). O exemplo completo está neste artigo.

Preciso de um número dedicado para usar a API?+

Não. A API não oficial conecta no seu próprio número via QR Code, como o WhatsApp Web. Se preferir não usar seu número pessoal, é possível usar um número virtual já com WhatsApp ativado.

Em quais linguagens posso integrar a API do WhatsApp?+

Em qualquer linguagem que faça requisições HTTP. Existem SDKs oficiais para Node.js/TypeScript e PHP, e a API REST funciona com Python, Go, Java, C#, Ruby e outras via cURL ou bibliotecas HTTP.