@banhosdev/whatsmiau-sdk

v0.1.2

Published

2 months ago

TypeScript SDK para integracao com a API Whatsmiau.

0High
0Medium
0Low

banhosdev

whatsapp whatsmiau sdk api typescript

@banhosdev/whatsmiau-sdk

SDK TypeScript para integrar com a API da Whatsmiau, uma API de WhatsApp nao oficial focada em estabilidade e eficiencia.

Este pacote foi modelado com base na documentacao publica da plataforma em whatsmiau.dev/docs, consultada em 2 de abril de 2026. O objetivo do SDK e oferecer uma interface tipada, organizada por recursos e pronta para uso em projetos Node.js e Bun.

Instalacao

npm install @banhosdev/whatsmiau-sdk

Ou com Bun:

bun add @banhosdev/whatsmiau-sdk

Requisitos

Node.js >=18 ou Bun com suporte a fetch
uma API Key valida gerada no dashboard da Whatsmiau
uma ou mais instancias configuradas na plataforma

Links uteis

Site: https://whatsmiau.dev
Documentacao oficial: https://whatsmiau.dev/docs
Base URL da API: https://api.whatsmiau.dev

Sumario

Visao geral

O SDK e organizado em modulos:

client.instances: criacao, conexao, listagem e exclusao de instancias
client.messages: envio de texto, midia, audio PTT, listas, botoes e reacoes
client.chat: presenca, leitura e verificacao de numeros
client.webhooks: configuracao e consulta de webhooks

Todos os recursos usam um cliente HTTP central com:

autenticacao por header apikey
timeout configuravel
headers customizados
beforeRequest para observabilidade e logging
suporte a fetch customizado

Criando o cliente

Forma mais simples

import { createWhatsmiauClient } from "@banhosdev/whatsmiau-sdk";

const client = createWhatsmiauClient({
  apiKey: process.env.WHATSMIAU_API_KEY!,
});

Forma explicita

import { WhatsmiauClient } from "@banhosdev/whatsmiau-sdk";

const client = new WhatsmiauClient({
  apiKey: process.env.WHATSMIAU_API_KEY!,
  baseUrl: "https://api.whatsmiau.dev",
  timeoutMs: 15_000,
  headers: {
    "x-app-name": "banhosdev-app",
  },
  beforeRequest: async ({ url, init }) => {
    console.log("Whatsmiau request:", init.method, url.toString());
  },
});

Autenticacao

A Whatsmiau usa API Key enviada no header apikey. O SDK injeta esse header automaticamente a partir de apiKey.

const client = createWhatsmiauClient({
  apiKey: "SUA_CHAVE_AQUI",
});

Para validar se a chave esta funcional, voce pode listar as instancias:

const response = await client.instances.list();
console.log(response);

Instancias

Cada instancia representa um numero/sessao conectada do WhatsApp.

Listar instancias

Mapeia GET /evolution/instances.

const instances = await client.instances.list();

Criar instancia

Mapeia POST /evolution/instance/create.

const created = await client.instances.create({
  instanceName: "Marketing01",
  qrcode: true,
});

Campos aceitos:

instanceName: nome unico da instancia
qrcode: se true, pede QR code no fluxo de criacao
token: token customizado da instancia

Conectar instancia

Mapeia GET /evolution/instance/connect/:id.

const connection = await client.instances.connect("64f1a2b3c4d5e6f7a8b9c0d1");

console.log(connection.data);

Use esse endpoint quando precisar recuperar o QR code ou dados de conexao de uma instancia ja criada.

Deletar instancia

Mapeia DELETE /evolution/instance/:id.

await client.instances.delete("64f1a2b3c4d5e6f7a8b9c0d1");

Mensagens

Os endpoints de mensagem usam o nome ou identificador da instancia na rota.

Enviar texto

Mapeia POST /message/sendText/:instance.

await client.messages.sendText("Marketing01", {
  number: "551199998888",
  text: "Ola! Sua integracao com a Whatsmiau esta funcionando.",
  delay: 1200,
  linkPreview: true,
});

Tambem suporta:

mentionsEveryOne
mentioned
quoted

Exemplo respondendo uma mensagem:

await client.messages.sendText("Marketing01", {
  number: "551199998888",
  text: "Respondendo sua mensagem anterior",
  quoted: {
    key: {
      id: "3EB0XXXXXXXX",
    },
  },
});

Enviar midia

Mapeia POST /message/sendMedia/:instance.

await client.messages.sendMedia("Marketing01", {
  number: "551199998888",
  mediatype: "image",
  media: "https://example.com/image.png",
  caption: "Confira a imagem",
});

Tipos suportados em mediatype:

image
video
document

Exemplo enviando documento:

await client.messages.sendMedia("Marketing01", {
  number: "551199998888",
  mediatype: "document",
  media: "https://example.com/catalogo.pdf",
  fileName: "catalogo.pdf",
  mimetype: "application/pdf",
});

Enviar audio PTT

Mapeia POST /message/sendWhatsAppAudio/:instance.

await client.messages.sendAudio("Marketing01", {
  number: "551199998888",
  audio: "https://example.com/voice.mp3",
  encoding: true,
});

Esse formato simula um audio enviado como voz do WhatsApp.

Enviar lista interativa

Mapeia POST /message/sendList/:instance.

await client.messages.sendList("Marketing01", {
  number: "551199998888",
  title: "Nossos Planos",
  description: "Escolha uma opcao abaixo:",
  buttonText: "Ver opcoes",
  footerText: "Whatsmiau Cloud",
  sections: [
    {
      title: "Planos",
      rows: [
        {
          title: "Starter",
          description: "R$ 30/mes - 1 instancia",
          rowId: "plan_starter",
        },
        {
          title: "Pro",
          description: "R$ 90/mes - 5 instancias",
          rowId: "plan_pro",
        },
      ],
    },
  ],
});

Enviar botoes interativos

Mapeia POST /message/sendButtons/:instance.

Botao de resposta rapida:

await client.messages.sendButtons("Marketing01", {
  number: "551199998888",
  title: "Confirmar Pedido",
  description: "Deseja confirmar o pedido #1234?",
  footer: "Whatsmiau Cloud",
  buttons: [
    {
      type: "reply",
      displayText: "Sim, confirmar",
      id: "confirm_yes",
    },
    {
      type: "reply",
      displayText: "Nao, cancelar",
      id: "confirm_no",
    },
  ],
});

Botao PIX:

await client.messages.sendButtons("Marketing01", {
  number: "551199998888",
  description: "Clique para pagar via PIX",
  buttons: [
    {
      type: "pix",
      displayText: "Pagar com PIX",
      currency: "BRL",
      name: "Banhos Dev",
      keyType: "email",
      key: "[email protected]",
    },
  ],
});

Enviar reacao

Mapeia POST /message/sendReaction/:instance.

await client.messages.sendReaction("Marketing01", {
  reaction: "❤️",
  key: {
    remoteJid: "[email protected]",
    id: "3EB0XXXXXXXX",
    fromMe: false,
  },
});

Chat e presenca

Enviar presenca

Mapeia POST /chat/sendPresence/:instance.

await client.chat.sendPresence("Marketing01", {
  number: "551199998888",
  presence: "composing",
  type: "text",
  delay: 3000,
});

Valores suportados:

presence: composing ou available
type: text ou audio

Marcar como lido

Mapeia POST /chat/markMessageAsRead/:instance.

await client.chat.markAsRead("Marketing01", {
  readMessages: [
    {
      remoteJid: "[email protected]",
      id: "3EB0XXXXXXXX",
    },
  ],
});

Em grupos, informe tambem sender.

Verificar numeros

Mapeia POST /chat/whatsappNumbers/:instance.

const result = await client.chat.verifyNumbers("Marketing01", {
  numbers: ["551199998888", "551199997777"],
});

console.log(result.data);

Webhooks

Os webhooks permitem receber eventos em tempo real enviados pela Whatsmiau para sua URL HTTP.

Configurar webhook

Mapeia POST /webhook/set/:instance.

await client.webhooks.set("Marketing01", {
  webhook: {
    enabled: true,
    url: "https://meusite.com/webhook",
    events: ["messages.upsert", "connection.update"],
    headers: {
      Authorization: "Bearer meu_token",
    },
    byEvents: true,
    base64: false,
  },
});

Campos suportados em webhook:

enabled
url
events
headers
byEvents
base64

Consultar webhook

Mapeia GET /webhook/find/:instance.

const webhook = await client.webhooks.find("Marketing01");
console.log(webhook.data);

Tipando o payload do webhook

O SDK exporta o envelope generico WhatsmiauWebhookEnvelope e um tipo especifico para messages.upsert.

import type {
  MessagesUpsertWebhook,
  WhatsmiauWebhookEnvelope,
} from "@banhosdev/whatsmiau-sdk";

function handleWebhook(payload: WhatsmiauWebhookEnvelope) {
  if (payload.event === "messages.upsert") {
    const event = payload as MessagesUpsertWebhook;
    console.log(event.data.messageType);
    console.log(event.data.message.conversation);
  }
}

Estrutura do envelope

type WhatsmiauWebhookEnvelope<TData = unknown> = {
  event: string;
  instance: string;
  data: TData;
  date_time: string;
  sender?: string;
  server_url?: string;
};

Evento `messages.upsert`

O tipo MessagesUpsertWebhook cobre os campos documentados para mensagens recebidas/enviadas, incluindo:

key
pushName
status
message
mediaUrl
messageType
messageTimestamp
instanceId
contextInfo

Dentro de message, o SDK ja tipa as variantes documentadas:

conversation
imageMessage
videoMessage
audioMessage
documentMessage
reactionMessage
contactMessage
listResponseMessage

Tratamento de erros

Erros HTTP da API sao encapsulados em WhatsmiauApiError.

import {
  WhatsmiauApiError,
  createWhatsmiauClient,
} from "@banhosdev/whatsmiau-sdk";

const client = createWhatsmiauClient({
  apiKey: process.env.WHATSMIAU_API_KEY!,
});

try {
  await client.instances.list();
} catch (error) {
  if (error instanceof WhatsmiauApiError) {
    console.error(error.status, error.statusText, error.body);
  }
}

Tipos exportados

O pacote exporta os principais tipos de request e webhook para uso em apps, backends e middlewares:

ApiResponse
InstanceCreateParams
InstanceRecord
InstanceConnectionPayload
SendTextParams
MediaMessageParams
SendAudioParams
ListMessageParams
ButtonMessageParams
ReactionMessageParams
PresenceParams
MarkMessagesAsReadParams
VerifyNumbersParams
WebhookConfigParams
WhatsmiauWebhookEnvelope
MessagesUpsertWebhook

Fluxo recomendado

Um fluxo tipico de uso com a API Whatsmiau fica assim:

criar o cliente com sua apiKey
validar credenciais com client.instances.list()
criar uma instancia com client.instances.create()
conectar a instancia com client.instances.connect()
enviar mensagens com client.messages.*
configurar webhooks com client.webhooks.set()

Observacoes

A documentacao publica da Whatsmiau detalha melhor os contratos de request do que os schemas completos de response.
Por isso, o SDK mantem requests fortemente tipados e respostas com flexibilidade quando o payload exato nao e explicitado na documentacao.
Os endpoints e tipos foram alinhados com a documentacao publica da versao v2.1.
Para detalhes operacionais da plataforma, consulte a documentacao oficial em whatsmiau.dev/docs.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@banhosdev/whatsmiau-sdk

Instalacao

Requisitos

Links uteis

Sumario

Visao geral

Criando o cliente

Forma mais simples

Forma explicita

Autenticacao

Instancias

Listar instancias

Criar instancia

Conectar instancia

Deletar instancia

Mensagens

Enviar texto

Enviar midia

Enviar audio PTT

Enviar lista interativa

Enviar botoes interativos

Enviar reacao

Chat e presenca

Enviar presenca

Marcar como lido

Verificar numeros

Webhooks

Configurar webhook

Consultar webhook

Tipando o payload do webhook

Estrutura do envelope

Evento messages.upsert

Tratamento de erros

Tipos exportados

Fluxo recomendado

Observacoes

Evento `messages.upsert`