painelzap
v0.3.0
Published
SDK oficial do painelzap: envio de mensagens e midia pelo WhatsApp, grupos, historico com status de entrega, validacao de numero, configuracao e verificacao de webhooks.
Maintainers
Readme
painelzap
SDK oficial do painelzap para Node.js: envio de mensagens e mídia pelo WhatsApp, grupos, validação de número e verificação de webhooks.
Sem dependências — usa o fetch nativo do Node 18+.
npm install painelzapComeçando
Pegue a appkey em Apps → Integração e a authkey no seu perfil.
import { Painelzap } from 'painelzap';
const zap = new Painelzap({
authkey: process.env.PAINELZAP_AUTHKEY!,
appkey: process.env.PAINELZAP_APPKEY!,
});
await zap.messages.send({ to: '5531988888888', message: 'Olá! Sua entrega chega hoje.' });Mensagens
// Texto
await zap.messages.send({ to: '5531988888888', message: 'Olá!' });
// Template, com placeholders
await zap.messages.send({
to: '5531988888888',
templateId: 'uuid-do-template',
variables: { nome: 'Maria', pedido: '1234' },
});Mídia
Por URL pública (o endereço precisa resolver para um IP público):
await zap.messages.sendMedia({
to: '5531988888888',
url: 'https://exemplo.com/nota-fiscal.pdf',
message: 'Segue sua nota fiscal',
});Por upload:
import { readFile } from 'node:fs/promises';
await zap.messages.sendMedia({
to: '5531988888888',
file: await readFile('./foto.jpg'),
fileName: 'foto.jpg',
});Áudio como mensagem de voz (aquela com a onda sonora, não anexo). O WhatsApp espera ogg/opus — outros codecs podem não tocar em todos os aparelhos:
await zap.messages.sendMedia({
to: '5531988888888',
url: 'https://exemplo.com/recado.ogg',
ptt: true,
});O tipo é deduzido pela extensão; use mediaType (image | video | audio | document) para forçar.
Confirmar que a mensagem chegou
Todo envio devolve message_id. Guarde-o e acompanhe o evento message.status:
const { message_id } = await zap.messages.send({ to: '5531988888888', message: 'Olá!' });
sentnão é entrega. Ele significa apenas que o servidor do WhatsApp aceitou a mensagem. Entrega no aparelho édelivered. Uma mensagem parada emsentpor muito tempo não chegou ao destinatário.A progressão é
sent→delivered→read(eplayedem áudio);errorindica falha.
Histórico da conversa
const mensagens = await zap.messages.history({ chatJid: '5531988888888', limit: 50 });
for (const m of mensagens) {
console.log(m.from_me ? 'eu' : 'ele', m.message, m.status);
}Vem das mais recentes para as mais antigas, incluindo o que você enviou (com o status de entrega; nas recebidas o status é null). Para paginar, use before com o sent_at da última linha:
const anteriores = await zap.messages.history({
chatJid: '5531988888888',
before: mensagens[mensagens.length - 1].sent_at,
});Duas limitações que valem saber: o histórico guarda os últimos 30 dias e começa a partir de quando o recurso foi ativado — o WhatsApp não devolve conversas anteriores ao pareamento. E o arquivo da mídia não fica guardado (só o tipo e o nome); para receber a mídia, use o webhook.
Grupos
const grupos = await zap.groups.list();
const grupo = await zap.groups.get(grupos[0].id);
console.log(grupo.name, grupo.participants.length);
await zap.groups.send({ groupId: grupos[0].id, message: 'Bom dia, time!' });Sobre os participantes: o WhatsApp migrou os contatos para LID, então
participant.idvem como...@lid, que não é telefone. O camponumbertraz o telefone quando o WhatsApp o expõe, e vemnullquando não. Useidcomo chave estável.
Validar número
Não envia mensagem e não consome a cota do plano:
const { exists } = await zap.numbers.check('5531988888888');
if (!exists) return;Webhooks
Configure pelo painel em Dispositivos → editar dispositivo → Webhook, ou pelo SDK:
const config = await zap.webhook.set({
url: 'https://meu.site/webhook',
events: ['message.received', 'message.group'],
});
console.log(config.webhook_secret); // guarde: é com ele que você confere a assinatura
await zap.webhook.get(); // configuração atual (não devolve o segredo)
await zap.webhook.remove(); // desliga a entregaSem events, o webhook recebe todos. Reconfigurar não troca o segredo, então chamar set de novo é seguro — inclusive para reler o segredo, que o get não devolve.
A URL precisa ser um endereço http(s) público: endereço de rede interna (localhost, 10.x, metadata da nuvem, nome de container) é recusado com 422.
Cada entrega vem assinada no header X-Painelzap-Signature.
Use o corpo cru. Se você passar o objeto já parseado e re-serializado, os bytes mudam e a assinatura nunca bate.
import express from 'express';
import { webhooks, type WebhookMensagem } from 'painelzap';
const app = express();
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
let evento;
try {
evento = webhooks.parse<WebhookMensagem['data']>({
body: req.body,
signature: req.header('X-Painelzap-Signature'),
secret: process.env.PAINELZAP_WEBHOOK_SECRET!,
});
} catch {
return res.sendStatus(401);
}
// Responda rápido: fora da faixa 2xx a entrega é retentada
// 5 vezes (10s, 1min, 5min, 15min).
res.sendStatus(200);
if (evento.event === 'message.received' && evento.data.media?.url) {
// A mídia fica disponível por 3 dias — baixe e guarde do seu lado.
baixar(evento.data.media.url);
}
});Prefere decidir você mesmo o que fazer quando a assinatura não confere? Use webhooks.verify(...), que devolve boolean em vez de lançar.
Eventos
| event | Quando dispara |
|---|---|
| message.received | mensagem recebida na conversa individual |
| message.group | mensagem em grupo — group_id e author preenchidos |
| message.status | mudou o status do que você enviou — data traz message_id, chat_jid e status |
| session.status | dispositivo conectou ou caiu (data.status) |
| webhook.test | botão Send test event da tela do dispositivo |
data.type é text, image, audio, video, document ou sticker. Mídia sem legenda chega com message: null.
Erros
Toda falha vira PainelzapError, com a mensagem que a API devolveu:
import { PainelzapError } from 'painelzap';
try {
await zap.messages.send({ to: '5531988888888', message: 'Olá' });
} catch (erro) {
if (erro instanceof PainelzapError) {
if (erro.naoAutorizado) { /* chave inválida, app de outra conta, ou cota estourada */ }
if (erro.invalido) { /* parâmetro faltando — veja erro.body */ }
console.error(erro.status, erro.message, erro.body);
}
}PainelzapTimeoutError (subclasse) é lançado quando a requisição passa do timeout, que por padrão é 30s.
Opções
new Painelzap({
authkey: '...',
appkey: '...',
baseUrl: 'https://painelzap.com', // instância própria
timeout: 30000,
fetch: meuFetch, // proxy, testes, runtime sem fetch global
});Licença
MIT
