# Como criar e integrar uma API de WhatsApp (cURL, Node.js e PHP)

> Tutorial passo a passo para integrar uma API de WhatsApp: conectar o número por QR Code e enviar sua primeira mensagem com cURL, Node.js (SDK oficial) e PHP. Com exemplos de código prontos.

**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**:

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

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

```bash
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

```bash
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:

```bash
npm i @raphaelvserafim/client-api-whatsapp
```

E envie:

```ts
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
<?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](https://github.com/raphaelvserafim/client-php-api-wa-me).

## 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:

```bash
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](/blog/como-enviar-mensagem-whatsapp-api) — recursos avançados;
- A [documentação completa da API](/docs) — todos os endpoints;
- [API não oficial do WhatsApp: é segura?](/blog/api-nao-oficial-whatsapp) — 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.