API completa para integração com WhatsApp. Conecte seus sistemas de forma simples e segura.
Todas as requisições à API devem incluir uma chave de autenticação no header.
apikey: SUA_API_KEY_AQUI
.env através da variável AUTHENTICATION_API_KEY
| Header | Valor | Obrigatório |
|---|---|---|
apikey |
Sua chave de API | ✅ Sim |
Content-Type |
application/json |
✅ Sim (para POST/PUT) |
Uma instância representa uma conexão com o WhatsApp. Você pode criar múltiplas instâncias para gerenciar diferentes números.
Cria uma nova instância do WhatsApp.
{
"instanceName": "minha-instancia",
"integration": "WHATSAPP-BAILEYS",
"qrcode": true,
"webhook": {
"url": "https://seu-sistema.com/webhook",
"byEvents": true,
"events": [
"MESSAGES_UPSERT",
"CONNECTION_UPDATE",
"QRCODE_UPDATED"
]
}
}
curl -X POST "http://localhost:8080/instance/create" \
-H "apikey: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instanceName": "minha-instancia",
"integration": "WHATSAPP-BAILEYS",
"qrcode": true
}'
Obtém o QR Code para conectar uma instância ao WhatsApp.
curl -X GET "http://localhost:8080/instance/connect/minha-instancia" \
-H "apikey: SUA_API_KEY"
Verifica o status de conexão de uma instância.
{
"instance": {
"instanceName": "minha-instancia",
"state": "open"
}
}
open (conectado), close (desconectado), connecting (conectando)
Lista todas as instâncias cadastradas.
Remove uma instância permanentemente.
Endpoints para enviar diferentes tipos de mensagens via WhatsApp.
Envia uma mensagem de texto simples.
{
"number": "5511999999999",
"text": "Olá! Esta é uma mensagem de teste.",
"delay": 1200
}
5511999999999
const response = await fetch('http://localhost:8080/message/sendText/minha-instancia', {
method: 'POST',
headers: {
'apikey': 'SUA_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
number: '5511999999999',
text: 'Olá! Esta é uma mensagem de teste.'
})
});
const data = await response.json();
console.log(data);
Envia imagens, vídeos, áudios ou documentos.
{
"number": "5511999999999",
"mediatype": "image",
"mimetype": "image/png",
"caption": "Legenda da imagem",
"media": "https://exemplo.com/imagem.png"
}
| mediatype | Descrição |
|---|---|
image |
Imagens (PNG, JPG, etc.) |
video |
Vídeos (MP4, etc.) |
audio |
Áudios (MP3, OGG, etc.) |
document |
Documentos (PDF, DOC, etc.) |
POST /message/sendLocation/{instance}
Envia uma localização no mapa.
POST /message/sendContact/{instance}
Envia um cartão de contato.
POST /message/sendWhatsAppAudio/{instance}
Envia áudio como mensagem de voz.
POST /message/sendList/{instance}
Envia uma mensagem com lista de opções.
POST /message/sendButtons/{instance}
Envia mensagem com botões interativos.
POST /message/sendPoll/{instance}
Envia uma enquete para votação.
Endpoints para criar e gerenciar grupos do WhatsApp.
Cria um novo grupo.
{
"subject": "Nome do Grupo",
"description": "Descrição do grupo",
"participants": [
"5511999999999",
"5511888888888"
]
}
GET /group/fetchAllGroups/{instance}
POST /group/updateParticipant/{instance}
GET /group/inviteCode/{instance}
DELETE /group/leaveGroup/{instance}
Configure webhooks para receber notificações em tempo real sobre eventos do WhatsApp.
{
"webhook": {
"enabled": true,
"url": "https://seu-sistema.com/webhook",
"byEvents": true,
"base64": false,
"events": [
"MESSAGES_UPSERT",
"MESSAGES_UPDATE",
"CONNECTION_UPDATE",
"QRCODE_UPDATED",
"SEND_MESSAGE"
]
}
}
| Evento | Descrição |
|---|---|
MESSAGES_UPSERT |
Nova mensagem recebida |
MESSAGES_UPDATE |
Mensagem atualizada (lida, entregue, etc.) |
CONNECTION_UPDATE |
Status da conexão alterado |
QRCODE_UPDATED |
Novo QR Code gerado |
SEND_MESSAGE |
Mensagem enviada com sucesso |
CONTACTS_UPDATE |
Contato atualizado |
GROUPS_UPSERT |
Grupo criado ou atualizado |
{
"event": "messages.upsert",
"instance": "minha-instancia",
"data": {
"key": {
"remoteJid": "5511999999999@s.whatsapp.net",
"fromMe": false,
"id": "3EB0..."
},
"pushName": "Nome do Contato",
"message": {
"conversation": "Olá, tudo bem?"
},
"messageType": "conversation",
"messageTimestamp": 1705849200
}
}
A API retorna códigos HTTP padrão para indicar sucesso ou falha.
| Código | Status | Descrição |
|---|---|---|
200 |
OK | Requisição bem-sucedida |
201 |
Created | Recurso criado com sucesso |
400 |
Bad Request | Dados inválidos na requisição |
401 |
Unauthorized | API Key inválida ou ausente |
404 |
Not Found | Instância ou recurso não encontrado |
500 |
Internal Error | Erro interno do servidor |
{
"status": 401,
"error": "Unauthorized",
"message": "Invalid API key"
}
Exemplos práticos de como integrar seu sistema com a Evolution API.
const API_URL = 'http://localhost:8080';
const API_KEY = 'SUA_API_KEY';
// Classe para gerenciar a API
class EvolutionAPI {
constructor(apiUrl, apiKey) {
this.apiUrl = apiUrl;
this.headers = {
'apikey': apiKey,
'Content-Type': 'application/json'
};
}
async createInstance(instanceName) {
const response = await fetch(`${this.apiUrl}/instance/create`, {
method: 'POST',
headers: this.headers,
body: JSON.stringify({
instanceName,
integration: 'WHATSAPP-BAILEYS',
qrcode: true
})
});
return response.json();
}
async sendText(instanceName, number, text) {
const response = await fetch(`${this.apiUrl}/message/sendText/${instanceName}`, {
method: 'POST',
headers: this.headers,
body: JSON.stringify({ number, text })
});
return response.json();
}
async getConnectionState(instanceName) {
const response = await fetch(`${this.apiUrl}/instance/connectionState/${instanceName}`, {
headers: this.headers
});
return response.json();
}
}
// Uso
const api = new EvolutionAPI(API_URL, API_KEY);
// Criar instância
const instance = await api.createInstance('meu-bot');
// Enviar mensagem
const result = await api.sendText('meu-bot', '5511999999999', 'Olá!');
import requests
API_URL = 'http://localhost:8080'
API_KEY = 'SUA_API_KEY'
headers = {
'apikey': API_KEY,
'Content-Type': 'application/json'
}
# Criar instância
def create_instance(instance_name):
response = requests.post(
f'{API_URL}/instance/create',
headers=headers,
json={
'instanceName': instance_name,
'integration': 'WHATSAPP-BAILEYS',
'qrcode': True
}
)
return response.json()
# Enviar mensagem de texto
def send_text(instance_name, number, text):
response = requests.post(
f'{API_URL}/message/sendText/{instance_name}',
headers=headers,
json={
'number': number,
'text': text
}
)
return response.json()
# Exemplo de uso
instance = create_instance('meu-bot')
print(instance)
result = send_text('meu-bot', '5511999999999', 'Olá do Python!')
print(result)
<?php
$apiUrl = 'http://localhost:8080';
$apiKey = 'SUA_API_KEY';
function sendRequest($endpoint, $method = 'GET', $data = null) {
global $apiUrl, $apiKey;
$ch = curl_init($apiUrl . $endpoint);
$headers = [
'apikey: ' . $apiKey,
'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
if ($method === 'POST') {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
}
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// Enviar mensagem
function sendText($instanceName, $number, $text) {
return sendRequest("/message/sendText/{$instanceName}", 'POST', [
'number' => $number,
'text' => $text
]);
}
// Exemplo de uso
$result = sendText('meu-bot', '5511999999999', 'Olá do PHP!');
print_r($result);
?>
const express = require('express');
const app = express();
app.use(express.json());
// Endpoint para receber webhooks
app.post('/webhook', (req, res) => {
const { event, instance, data } = req.body;
console.log(`Evento: ${event}`);
console.log(`Instância: ${instance}`);
switch (event) {
case 'messages.upsert':
// Nova mensagem recebida
const message = data.message;
const from = data.key.remoteJid;
console.log(`Mensagem de ${from}:`, message);
// Processar mensagem...
break;
case 'connection.update':
// Status da conexão alterado
console.log(`Status: ${data.state}`);
break;
case 'qrcode.updated':
// Novo QR Code
console.log('QR Code atualizado');
break;
}
res.status(200).json({ received: true });
});
app.listen(3000, () => {
console.log('Webhook server running on port 3000');
});