npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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.

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 painelzap

Começ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á!' });

sent não é entrega. Ele significa apenas que o servidor do WhatsApp aceitou a mensagem. Entrega no aparelho é delivered. Uma mensagem parada em sent por muito tempo não chegou ao destinatário.

A progressão é sent → delivered → read (e played em áudio); error indica 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.id vem como ...@lid, que não é telefone. O campo number traz o telefone quando o WhatsApp o expõe, e vem null quando não. Use id como 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 entrega

Sem 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