Visão geral
API REST para integração com o painel WhatsAppHenry
A API v1 permite que aplicações externas (PHP, Python, JavaScript, etc.) gerenciem instâncias WhatsApp sem precisar acessar o painel manualmente. Toda comunicação é feita via HTTPS + Bearer Token.
Base URL: http://localhost:3000/api/v1
Formato: application/json
Versão: v1
Autenticação
Como obter e usar seu token de segurança
Para usar a API, você precisa de um token de segurança. Após fazer login no painel, vá em Configurações → Token de Segurança e copie seu token pessoal.
Cada usuário tem seu próprio token. Gerar um novo token invalida o anterior imediatamente.
Mantenha seu token em segredo — ele dá acesso total à API.
Inclua o token em toda requisição:
Authorization: Bearer seu_token_aqui_32_caracteres_hex
Formato de respostas
Estrutura padrão de todas as respostas
Sucesso (2xx)
{
"success": true,
"data": {
// conteúdo varia por endpoint
}
}
Erro (4xx / 5xx)
{
"success": false,
"error": "Mensagem de erro"
}
Erros comuns
Códigos HTTP e seus significados
| Código | Significado | Solução |
|---|---|---|
401 | Token ausente ou inválido | Verifique o header Authorization: Bearer <token> |
400 | Parâmetro inválido | Verifique os campos obrigatórios no body |
404 | Recurso não encontrado | Verifique o nome da instância |
409 | Conflito (ex: instância já existe) | Use um nome diferente |
500 | Erro interno / Evolution API offline | Verifique se a Evolution API está rodando |
Criar instância
Cria uma nova instância WhatsApp na Evolution API
POST
/api/v1/instances
Cria instância e retorna dados para conexão
Parâmetros do body (JSON):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
instanceName |
string |
obrigatório | Nome único da instância (sem espaços; use underscore) |
Requisição:
POST /api/v1/instances
Authorization: Bearer seu_token
Content-Type: application/json
{
"instanceName": "meu_whatsapp"
}
Resposta de sucesso (201):
{
"success": true,
"data": {
"instance": {
"instanceName": "meu_whatsapp",
"status": "created"
}
}
}
Listar instâncias
Retorna todas as instâncias WhatsApp cadastradas
GET
/api/v1/instances
Lista todas as instâncias
Requisição:
GET /api/v1/instances
Authorization: Bearer seu_token
Resposta (200):
{
"success": true,
"data": {
"instances": [
{
"instanceName": "pessoal",
"connectionStatus": "open"
},
{
"instanceName": "empresa",
"connectionStatus": "close"
}
]
}
}
Obter QR Code
Gera e retorna o QR code para conectar uma instância
GET
/api/v1/instances/:name/qr
Retorna base64 do QR code
| Parâmetro | Tipo | Descrição |
|---|---|---|
:name | URL param | Nome da instância |
GET /api/v1/instances/meu_whatsapp/qr
Authorization: Bearer seu_token
Resposta (200):
{
"success": true,
"data": {
"qr": {
"base64": "data:image/png;base64,iVBOR...",
"code": "2@abc123..."
}
}
}
Status de conexão
Verifica se uma instância está conectada ao WhatsApp
GET
/api/v1/instances/:name/status
open = conectado | close = desconectado
GET /api/v1/instances/meu_whatsapp/status
Authorization: Bearer seu_token
Resposta (200):
{
"success": true,
"data": {
"status": {
"instance": { "instanceName": "meu_whatsapp", "state": "open" }
}
}
}
Exemplo PHP completo
Classe pronta para copiar e usar no seu projeto
<?php
class WhatsAppHenryAPI {
private $baseUrl;
private $token;
public function __construct($baseUrl, $token) {
$this->baseUrl = rtrim($baseUrl, '/');
$this->token = $token;
}
private function request($method, $endpoint, $body = null) {
$ch = curl_init($this->baseUrl . $endpoint);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $this->token,
]);
if ($body) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// Criar nova instância WhatsApp
public function criarInstancia($nome) {
return $this->request('POST', '/api/v1/instances', ['instanceName' => $nome]);
}
// Listar todas as instâncias
public function listarInstancias() {
return $this->request('GET', '/api/v1/instances');
}
// Obter QR Code para conectar
public function obterQRCode($nome) {
return $this->request('GET', '/api/v1/instances/' . $nome . '/qr');
}
// Verificar status de conexão
public function verificarStatus($nome) {
return $this->request('GET', '/api/v1/instances/' . $nome . '/status');
}
}
// ── Uso ──────────────────────────────────────────────────────────────
$api = new WhatsAppHenryAPI(
'http://localhost:3000', // URL do painel
'seu_token_de_32_caracteres_aqui' // Token de Segurança
);
// 1. Criar instância para um novo cliente
$resultado = $api->criarInstancia('cliente_joao');
if ($resultado['success']) {
echo "Instância criada: " . $resultado['data']['instance']['instanceName'];
// 2. Obter QR Code para o cliente escanear
$qr = $api->obterQRCode('cliente_joao');
if ($qr['success']) {
$base64 = $qr['data']['qr']['base64'];
echo '
';
}
} else {
echo "Erro: " . $resultado['error'];
}
// 3. Verificar se o cliente conectou
$status = $api->verificarStatus('cliente_joao');
$state = $status['data']['status']['instance']['state'] ?? 'unknown';
echo "Status: " . ($state === 'open' ? 'Conectado ✓' : 'Aguardando conexão...');
?>
Exemplos cURL
Para testar rapidamente via linha de comando
Criar instância:
curl -X POST http://localhost:3000/api/v1/instances \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"instanceName": "meu_whatsapp"}'
Listar instâncias:
curl http://localhost:3000/api/v1/instances \
-H "Authorization: Bearer SEU_TOKEN"
Status de conexão:
curl http://localhost:3000/api/v1/instances/meu_whatsapp/status \
-H "Authorization: Bearer SEU_TOKEN"
JavaScript (fetch)
Para uso em Node.js ou frontend
const BASE = 'http://localhost:3000';
const TOKEN = 'seu_token_aqui';
const headers = {
'Content-Type': 'application/json',
'Authorization': `Bearer ${TOKEN}`,
};
// Criar instância
const res = await fetch(`${BASE}/api/v1/instances`, {
method: 'POST',
headers,
body: JSON.stringify({ instanceName: 'meu_whatsapp' }),
});
const json = await res.json();
console.log(json.data.instance);
// Verificar status
const status = await fetch(`${BASE}/api/v1/instances/meu_whatsapp/status`, { headers });
const { data } = await status.json();
console.log(data.status.instance.state); // 'open' ou 'close'