Referência da API
API de WhatsApp
Envie mensagens pelo seu número de WhatsApp com chamadas HTTP simples. Cada sessão é uma conexão independente, com plano, validade, chave e limites próprios.
https://dev-api.primux.cloud AuthBearer FormatoJSON · UTF-8https://dev-api.primux.cloud/v1/whatsappVisão geral
A API conecta um número de WhatsApp (a sessão) à sua aplicação. Você contrata a sessão no console, conecta o número lendo um QR code ou digitando um código no celular e passa a enviar mensagens com uma chave de API.
- Envio de texto para contatos e para grupos.
- Envio de link com prévia (título, imagem e descrição da página).
- Consulta da situação da sessão, dos grupos e do uso do dia e do mês.
{
"nome": "Atendimento",
"plano": "WhatsApp 1.000",
"estado": "conectada",
"numero": "5577999999999",
"valido_ate": "2026-12-03T14:30:00Z",
"limite_diario": 1000,
"limite_por_minuto": 20
}Início rápido
- Contrate uma sessão em Console › APIs e aguarde a confirmação do pagamento.
- Conecte o número: no celular, abra WhatsApp › Aparelhos conectados e leia o QR code, ou escolha conectar por código de 8 caracteres.
- Gere a chave de API na página da sessão (ela aparece uma única vez; guarde como uma senha).
- Faça a primeira chamada, trocando SUA_CHAVE pela chave gerada:
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}'<?php
$chave = getenv('PRIMUX_WHATSAPP_CHAVE');
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/mensagens');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $chave,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'para' => '77999999999',
'texto' => 'Olá! Seu pedido saiu para entrega.',
]),
]);
$corpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$resposta = json_decode($corpo, true);
if ($status === 200) {
echo "Enviada: " . $resposta['id'];
} else {
echo "Erro {$status}: " . $resposta['erro'] . ' - ' . $resposta['mensagem'];
}const chave = process.env.PRIMUX_WHATSAPP_CHAVE;
const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/mensagens', {
method: 'POST',
headers: {
'Authorization': `Bearer ${chave}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
para: '77999999999',
texto: 'Olá! Seu pedido saiu para entrega.',
}),
});
const dados = await resposta.json();
if (resposta.ok) {
console.log('Enviada:', dados.id);
} else {
console.error(`Erro ${resposta.status}: ${dados.erro} - ${dados.mensagem}`);
}import os
import requests
chave = os.environ["PRIMUX_WHATSAPP_CHAVE"]
resposta = requests.post(
"https://dev-api.primux.cloud/v1/whatsapp/mensagens",
headers={"Authorization": f"Bearer {chave}"},
json={"para": "77999999999", "texto": "Olá! Seu pedido saiu para entrega."},
timeout=15,
)
dados = resposta.json()
if resposta.ok:
print("Enviada:", dados["id"])
else:
print(f"Erro {resposta.status_code}: {dados['erro']} - {dados['mensagem']}")Autenticação
Envie a chave da sessão no cabeçalho Authorization, no formato Bearer. A chave é gerada no painel e mostrada uma única vez; gerar outra invalida a anterior. Guarde-a como uma senha e nunca a coloque em páginas ou aplicativos públicos.
Authorization: Bearer pxa_0123456789abcdef0123456789abcdef0123456789abcdefEndereço e formato
Endereço da API: https://dev-api.primux.cloud
- Todas as chamadas usam JSON em UTF-8 (cabeçalho Content-Type: application/json nos POST).
- Campos que a API não conhece são recusados com o erro corpo_invalido.
- Números aceitam máscara e símbolos; sem o código do país, o Brasil (+55) é assumido. Exemplos válidos: 77999999999, (77) 99999-9999, +55 77 99999-9999.
- Datas e horas vêm em UTC, no formato ISO 8601 (2026-11-03T14:30:00Z).
{
"id": "3EB01931ACD50366D198B8",
"estado": "enviada",
"enviada_em": "2026-11-03T14:30:00Z"
}Referência da API
Consultar a sessão
GET/v1/whatsapp/sessao
Situação da sessão: estado, número conectado, plano e validade. Use para saber se a sessão está conectada antes de enviar, e para ver o plano, a validade e os limites.
Esta rota não recebe corpo: só o cabeçalho de autenticação.
curl -X GET https://dev-api.primux.cloud/v1/whatsapp/sessao \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/sessao');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_WHATSAPP_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/sessao', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_WHATSAPP_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/whatsapp/sessao",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_WHATSAPP_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"nome": "Atendimento",
"plano": "WhatsApp 1.000",
"estado": "conectada",
"numero": "5577999999999",
"valido_ate": "2026-12-03T14:30:00Z",
"limite_diario": 1000,
"limite_por_minuto": 20
}Referência da API
Enviar mensagem
POST/v1/whatsapp/mensagens
Envia um texto para um contato (campos para e texto). Envia um texto para um contato. O campo para é o número do destinatário.
Parâmetros do corpo
paratexto obrigatório- Número do contato (com ou sem máscara e código do país).
textotexto obrigatório- Texto da mensagem, até 4096 caracteres.
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}'<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/mensagens');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => '{"para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_WHATSAPP_CHAVE'),
'Content-Type: application/json',
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/mensagens', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_WHATSAPP_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"para": "77999999999",
"texto": "Olá! Seu pedido saiu para entrega."
}),
});
const dados = await resposta.json();import os, requests
resposta = requests.post(
"https://dev-api.primux.cloud/v1/whatsapp/mensagens",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_WHATSAPP_CHAVE']}"},
json={
"para": "77999999999",
"texto": "Olá! Seu pedido saiu para entrega."
},
timeout=15,
)
dados = resposta.json(){
"id": "3EB01931ACD50366D198B8",
"estado": "enviada",
"enviada_em": "2026-11-03T14:30:00Z"
}Referência da API
Enviar mensagem a um grupo
POST/v1/whatsapp/grupos/mensagens
Envia um texto para um grupo (campos grupo e texto). Envia um texto para um grupo. Pegue o identificador do grupo na rota de grupos.
Parâmetros do corpo
grupotexto obrigatório- Identificador do grupo (use a rota de grupos para listar).
textotexto obrigatório- Texto da mensagem, até 4096 caracteres.
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/grupos/mensagens \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"grupo":"120363025246125486","texto":"Reunião às 15h."}'<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/grupos/mensagens');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => '{"grupo":"120363025246125486","texto":"Reunião às 15h."}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_WHATSAPP_CHAVE'),
'Content-Type: application/json',
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/grupos/mensagens', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_WHATSAPP_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"grupo": "120363025246125486",
"texto": "Reunião às 15h."
}),
});
const dados = await resposta.json();import os, requests
resposta = requests.post(
"https://dev-api.primux.cloud/v1/whatsapp/grupos/mensagens",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_WHATSAPP_CHAVE']}"},
json={
"grupo": "120363025246125486",
"texto": "Reunião às 15h."
},
timeout=15,
)
dados = resposta.json(){
"id": "3EB0A7C1D2E3F40516",
"estado": "enviada",
"enviada_em": "2026-11-03T14:31:10Z"
}Referência da API
Enviar link com prévia
POST/v1/whatsapp/mensagens/link
Envia um link com prévia para um contato ou grupo (para ou grupo, texto e url). Envia uma mensagem com um link; o WhatsApp mostra a prévia da página. Informe para (contato) ou grupo, nunca os dois.
Parâmetros do corpo
paratexto Um dos dois- Número do contato (com ou sem máscara e código do país).
grupotexto Um dos dois- Identificador do grupo (use a rota de grupos para listar).
textotexto obrigatório- Texto da mensagem, até 4096 caracteres.
urltexto obrigatório- Link público começando com http:// ou https://.
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens/link \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"para":"77999999999","texto":"Confira nossa novidade:","url":"https://exemplo.com.br/novidade"}'<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/mensagens/link');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => '{"para":"77999999999","texto":"Confira nossa novidade:","url":"https://exemplo.com.br/novidade"}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_WHATSAPP_CHAVE'),
'Content-Type: application/json',
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/mensagens/link', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_WHATSAPP_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"para": "77999999999",
"texto": "Confira nossa novidade:",
"url": "https://exemplo.com.br/novidade"
}),
});
const dados = await resposta.json();import os, requests
resposta = requests.post(
"https://dev-api.primux.cloud/v1/whatsapp/mensagens/link",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_WHATSAPP_CHAVE']}"},
json={
"para": "77999999999",
"texto": "Confira nossa novidade:",
"url": "https://exemplo.com.br/novidade"
},
timeout=15,
)
dados = resposta.json(){
"id": "3EB0C0FFEE12345678",
"estado": "enviada",
"enviada_em": "2026-11-03T14:32:40Z"
}Referência da API
Enviar imagem
POST/v1/whatsapp/mensagens/imagem
Envia uma imagem PNG ou JPEG (em base64, até 5 MB) para um contato ou grupo, com legenda opcional. O campo imagem leva o arquivo codificado em base64 (sem o prefixo data:). Aceita PNG e JPEG de até 5 MB. Informe para (contato) ou grupo, nunca os dois. A legenda aparece junto da imagem.
Parâmetros do corpo
paratexto Um dos dois- Número do contato (com ou sem máscara e código do país).
grupotexto Um dos dois- Identificador do grupo (use a rota de grupos para listar).
imagemtexto (base64) obrigatório- Imagem PNG ou JPEG em base64, até 5 MB (o corpo da requisição pode ter até 8 MB).
legendatexto opcional- Texto que acompanha a imagem ou o documento, até 4096 caracteres. Opcional.
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens/imagem \\
-H "Authorization: Bearer SUA_CHAVE" \\
-H "Content-Type: application/json" \\
-d "{\\"para\\":\\"77999999999\\",\\"imagem\\":\\"$(base64 -w0 comprovante.png)\\",\\"legenda\\":\\"Seu comprovante\\"}"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/mensagens/imagem');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_WHATSAPP_CHAVE'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'para' => '77999999999',
'imagem' => base64_encode(file_get_contents('comprovante.png')),
'legenda' => 'Seu comprovante',
]),
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);import { readFileSync } from 'node:fs';
const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/mensagens/imagem', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_WHATSAPP_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
para: '77999999999',
imagem: readFileSync('comprovante.png').toString('base64'),
legenda: 'Seu comprovante',
}),
});
const dados = await resposta.json();import base64, os, requests
with open("comprovante.png", "rb") as f:
conteudo = base64.b64encode(f.read()).decode()
resposta = requests.post(
"https://dev-api.primux.cloud/v1/whatsapp/mensagens/imagem",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_WHATSAPP_CHAVE']}"},
json={
"para": "77999999999",
"imagem": conteudo,
"legenda": "Seu comprovante",
},
timeout=60,
)
dados = resposta.json(){
"id": "3EB0D1E2F3A4B5C6D7",
"estado": "enviada",
"enviada_em": "2026-11-03T14:33:10Z"
}Referência da API
Enviar PDF
POST/v1/whatsapp/mensagens/documento
Envia um documento PDF (em base64, até 5 MB) para um contato ou grupo, com nome de arquivo e legenda opcionais. O campo documento leva o PDF codificado em base64 (sem prefixo), de até 5 MB. O campo arquivo define o nome que aparece no WhatsApp (a extensão .pdf é garantida). Informe para (contato) ou grupo, nunca os dois.
Parâmetros do corpo
paratexto Um dos dois- Número do contato (com ou sem máscara e código do país).
grupotexto Um dos dois- Identificador do grupo (use a rota de grupos para listar).
documentotexto (base64) obrigatório- PDF em base64, até 5 MB (o corpo da requisição pode ter até 8 MB).
arquivotexto opcional- Nome do arquivo que o destinatário vê, ex.: fatura-128.pdf. Opcional.
legendatexto opcional- Texto que acompanha a imagem ou o documento, até 4096 caracteres. Opcional.
curl -X POST https://dev-api.primux.cloud/v1/whatsapp/mensagens/documento \\
-H "Authorization: Bearer SUA_CHAVE" \\
-H "Content-Type: application/json" \\
-d "{\\"para\\":\\"77999999999\\",\\"documento\\":\\"$(base64 -w0 fatura-128.pdf)\\",\\"arquivo\\":\\"fatura-128.pdf\\",\\"legenda\\":\\"Sua fatura de novembro\\"}"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/mensagens/documento');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_WHATSAPP_CHAVE'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'para' => '77999999999',
'documento' => base64_encode(file_get_contents('fatura-128.pdf')),
'arquivo' => 'fatura-128.pdf',
'legenda' => 'Sua fatura de novembro',
]),
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);import { readFileSync } from 'node:fs';
const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/mensagens/documento', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_WHATSAPP_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
para: '77999999999',
documento: readFileSync('fatura-128.pdf').toString('base64'),
arquivo: 'fatura-128.pdf',
legenda: 'Sua fatura de novembro',
}),
});
const dados = await resposta.json();import base64, os, requests
with open("fatura-128.pdf", "rb") as f:
conteudo = base64.b64encode(f.read()).decode()
resposta = requests.post(
"https://dev-api.primux.cloud/v1/whatsapp/mensagens/documento",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_WHATSAPP_CHAVE']}"},
json={
"para": "77999999999",
"documento": conteudo,
"arquivo": "fatura-128.pdf",
"legenda": "Sua fatura de novembro",
},
timeout=60,
)
dados = resposta.json(){
"id": "3EB0E2F3A4B5C6D7E8",
"estado": "enviada",
"enviada_em": "2026-11-03T14:34:20Z"
}Referência da API
Listar grupos
GET/v1/whatsapp/grupos
Lista os grupos em que o número participa. Lista os grupos em que o número conectado participa, com identificador, nome e quantidade de participantes.
Esta rota não recebe corpo: só o cabeçalho de autenticação.
curl -X GET https://dev-api.primux.cloud/v1/whatsapp/grupos \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/grupos');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_WHATSAPP_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/grupos', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_WHATSAPP_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/whatsapp/grupos",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_WHATSAPP_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"grupos": [
{ "id": "120363025246125486", "nome": "Equipe", "participantes": 12 }
]
}Referência da API
Consultar o uso
GET/v1/whatsapp/uso
Uso do dia e do mês, por tipo, e o que resta do limite diário. Mostra quantas mensagens foram enviadas hoje e no mês, por tipo, e quanto resta do limite diário do plano.
Esta rota não recebe corpo: só o cabeçalho de autenticação.
curl -X GET https://dev-api.primux.cloud/v1/whatsapp/uso \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/whatsapp/uso');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_WHATSAPP_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/whatsapp/uso', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_WHATSAPP_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/whatsapp/uso",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_WHATSAPP_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"data": "2026-11-03",
"hoje": { "mensagens": 41, "mensagens_em_grupo": 3, "links": 6, "imagens": 2, "documentos": 1, "total": 53 },
"mes": { "mensagens": 812, "mensagens_em_grupo": 40, "links": 77, "imagens": 25, "documentos": 9, "total": 963 },
"limite_diario": 1000,
"restante_hoje": 947
}Erros
Todo erro traz um código estável (campo erro) e uma mensagem em português (campo mensagem).
| Status | Código | Quando acontece |
|---|---|---|
| 401 | chave_invalida | Chave ausente, errada ou mal formatada. |
| 403 | chave_de_outra_api | A chave pertence a outro tipo de API. |
| 403 | sessao_suspensa | A sessão foi suspensa por falta de pagamento. |
| 403 | sessao_cancelada | A sessão foi cancelada. |
| 409 | sessao_nao_conectada | A sessão ainda não foi conectada ao WhatsApp ou foi desconectada. |
| 422 | numero_invalido | O número informado não tem formato válido. |
| 422 | numero_sem_whatsapp | O número não tem WhatsApp. |
| 422 | grupo_invalido | Identificador de grupo inválido. |
| 422 | destino_invalido | Campo de destino na rota errada: contato em /mensagens, grupo em /grupos/mensagens. |
| 422 | texto_vazio | O texto é obrigatório. |
| 422 | texto_grande | O texto passa de 4096 caracteres. |
| 422 | url_invalida | Link inválido ou não público. |
| 422 | imagem_invalida | Imagem inválida: envie PNG ou JPEG de até 5 MB, em base64. |
| 422 | documento_invalido | Documento inválido: envie um PDF de até 5 MB, em base64. |
| 400 | corpo_invalido | JSON inválido ou com campos desconhecidos. |
| 429 | limite_por_minuto | Limite de envios por minuto do plano atingido. |
| 429 | limite_diario | Limite diário de envios do plano atingido. |
| 502 | falha_no_envio | O WhatsApp não aceitou a mensagem; tente de novo. |
| 503 | servico_indisponivel | O serviço não respondeu agora; tente de novo. |
{
"erro": "numero_sem_whatsapp",
"mensagem": "Este número não tem WhatsApp."
}Limites e boas práticas
- O plano define o limite de envios por dia (zera à meia-noite) e por minuto; acima dele a API responde 429.
- Números aceitam máscara; sem o código do país, o Brasil (+55) é assumido.
- Textos têm até 4096 caracteres; links precisam ser http ou https públicos.
- Envie só para quem autorizou receber mensagens. Spam é proibido e pode bloquear o seu número.
- Imagens e PDFs têm até 5 MB (base64 no corpo, até 8 MB); só PNG, JPEG e PDF são aceitos.
Boas práticas
- Consulte a rota de sessão antes de grandes envios: se o estado não for conectada, reconecte o número no console.
- Espalhe os envios no tempo em vez de disparar tudo de uma vez; respeite o limite por minuto do plano.
- Guarde o id devolvido em cada envio para rastrear a mensagem no seu sistema.
- Trate os códigos de erro (campo erro), nunca o texto da mensagem, que pode mudar.
- Mantenha o celular da sessão com internet e o WhatsApp atualizado.
Tentar de novo com segurança
Os erros 429 (limite), 502 (falha no envio) e 503 (serviço indisponível) podem ser repetidos com espera crescente. Os demais erros não melhoram sozinhos: corrija a requisição.
import time, requests
def enviar(url, chave, corpo, tentativas=4):
espera = 1
for _ in range(tentativas):
r = requests.post(url, headers={"Authorization": f"Bearer {chave}"}, json=corpo, timeout=15)
if r.status_code not in (429, 502, 503):
return r
time.sleep(espera) # limite por minuto, falha no envio ou serviço indisponível
espera *= 2
return rEstados da sessão
criada- A sessão foi criada e ainda não foi conectada ao WhatsApp.
aguardando_conexao- Aguardando a leitura do QR code ou a digitação do código no celular.
conectada- Pronta para enviar mensagens.
desconectada- O WhatsApp desconectou o aparelho (ou o celular ficou sem internet por muito tempo). Reconecte no console.
suspensa- Suspensa por falta de pagamento. Pague a renovação para a sessão voltar.
Perguntas frequentes
Posso usar o meu número pessoal?
Pode, mas recomendamos um número dedicado ao negócio: se o WhatsApp restringir o número por envio indevido, você não perde o seu contato pessoal.
A API recebe mensagens dos clientes?
Ainda não. A versão atual envia mensagens e consulta situação, grupos e uso. O recebimento (webhooks) entra em uma versão futura.
O que acontece se o celular ficar sem internet?
A sessão continua por um tempo, mas depois de muitos dias offline o WhatsApp pode desconectar o aparelho. Nesse caso o estado vira desconectada e basta reconectar.
Posso enviar imagens, áudios ou documentos?
Nesta versão, só texto e links com prévia.
Como troco a chave?
Na página da sessão, gere uma nova chave. A anterior deixa de valer imediatamente.