{"_id":"@banhosdev/whatsmiau-sdk","_rev":"3-11e5993d06d27fd07f6d84d38eeb52fb","name":"@banhosdev/whatsmiau-sdk","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@banhosdev/whatsmiau-sdk","version":"0.1.0","keywords":["whatsapp","whatsmiau","sdk","api","typescript"],"author":{"name":"banhosdev"},"license":"MIT","_id":"@banhosdev/whatsmiau-sdk@0.1.0","maintainers":[{"name":"banhosdev","email":"sergiobanhosf@gmail.com"}],"homepage":"https://whatsmiau.dev/docs","dist":{"shasum":"f988321f88e1d3982e37e45fb6b00e1dd4c5fb53","tarball":"https://registry.npmjs.org/@banhosdev/whatsmiau-sdk/-/whatsmiau-sdk-0.1.0.tgz","fileCount":8,"integrity":"sha512-bI9sr5d28w7ufJJFqvq7WxlucfV+1pu7CscV/x7avfKNQyJAC1snoOkYmdk8fIgfW53635o45qmR+DX/i6dvEQ==","signatures":[{"sig":"MEUCICXaN1JNx6I/Q//HevlStCJ40ZBmS6L49TvFeYW+1HAKAiEAl9Ncby09SW34oW5nPZqPqY04ImxO/PJMKlofqgVCdHY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78289},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","test":"vitest run","build":"tsup","clean":"rm -rf dist"},"_npmUser":{"name":"banhosdev","email":"sergiobanhosf@gmail.com"},"repository":{"type":"git"},"_npmVersion":"10.9.3","description":"TypeScript SDK para integracao com a API Whatsmiau.","directories":{},"sideEffects":false,"_nodeVersion":"22.18.0","_hasShrinkwrap":false,"packageManager":"bun@1.2.19","devDependencies":{"tsup":"^8.3.5","vitest":"^3.2.4","typescript":"^5.9.2","@types/node":"^24.5.2"},"_npmOperationalInternal":{"tmp":"tmp/whatsmiau-sdk_0.1.0_1775171198392_0.9935230780972699","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@banhosdev/whatsmiau-sdk","version":"0.1.1","keywords":["whatsapp","whatsmiau","sdk","api","typescript"],"author":{"name":"banhosdev"},"license":"MIT","_id":"@banhosdev/whatsmiau-sdk@0.1.1","maintainers":[{"name":"banhosdev","email":"sergiobanhosf@gmail.com"}],"homepage":"https://whatsmiau.dev/docs","dist":{"shasum":"ea3f2b6b890a94c3153c7a2d05cf142ed7615ada","tarball":"https://registry.npmjs.org/@banhosdev/whatsmiau-sdk/-/whatsmiau-sdk-0.1.1.tgz","fileCount":8,"integrity":"sha512-NOMCWjWrgEO5YDhZO2W1A63JMbI6IH3BTwCZ6hZPhLEyfqNZ0s2nfCeTWpBbJJW3InGRN+ED82G6EZ4zB2ZgkQ==","signatures":[{"sig":"MEUCIFnOV1x+yJc81JfBURAPsONDqTEF7pq/20Xtq6VcWH5ZAiEAnrjEhc7l4oYOwySTmn++fvXtfZkrCqJSdW3sWExHI3g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":88047},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","test":"vitest run","build":"tsup","clean":"rm -rf dist"},"_npmUser":{"name":"banhosdev","email":"sergiobanhosf@gmail.com"},"repository":{"type":"git"},"_npmVersion":"10.9.3","description":"TypeScript SDK para integracao com a API Whatsmiau.","directories":{},"sideEffects":false,"_nodeVersion":"22.18.0","_hasShrinkwrap":false,"packageManager":"bun@1.2.19","devDependencies":{"tsup":"^8.3.5","vitest":"^3.2.4","typescript":"^5.9.2","@types/node":"^24.5.2"},"_npmOperationalInternal":{"tmp":"tmp/whatsmiau-sdk_0.1.1_1775171411780_0.8674196134204413","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@banhosdev/whatsmiau-sdk","version":"0.1.2","description":"TypeScript SDK para integracao com a API Whatsmiau.","keywords":["whatsapp","whatsmiau","sdk","api","typescript"],"homepage":"https://whatsmiau.dev/docs","repository":{"type":"git"},"license":"MIT","author":{"name":"banhosdev"},"type":"module","packageManager":"bun@1.2.19","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=18"},"scripts":{"build":"tsup","clean":"rm -rf dist","dev":"tsup --watch","lint":"tsc --noEmit","test":"vitest run"},"devDependencies":{"@types/node":"^24.5.2","tsup":"^8.3.5","typescript":"^5.9.2","vitest":"^3.2.4"},"_id":"@banhosdev/whatsmiau-sdk@0.1.2","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-GAb8EyCLSCFxcwmI13IICWEWXK2XpwAfJBSug+bxod08i5uocYAzaM4QAqdj2mOCdfSxDjTmo0snoT+N+otoLw==","shasum":"1fe85d0c4b901583f70d206c1698b1d66f66c0e6","tarball":"https://registry.npmjs.org/@banhosdev/whatsmiau-sdk/-/whatsmiau-sdk-0.1.2.tgz","fileCount":8,"unpackedSize":88047,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIARBwCq6YGWPw/5xEv+xcGxNhpw+FS8mLxvMZpHvoS5LAiBkEHU17V70MneQtT7d66KHH4LeSylVLVr+Qn6+SQ6AHQ=="}]},"_npmUser":{"name":"banhosdev","email":"sergiobanhosf@gmail.com"},"directories":{},"maintainers":[{"name":"banhosdev","email":"sergiobanhosf@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/whatsmiau-sdk_0.1.2_1775172237632_0.3276615984210114"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-02T23:06:38.278Z","modified":"2026-04-02T23:23:58.226Z","0.1.0":"2026-04-02T23:06:38.569Z","0.1.1":"2026-04-02T23:10:11.958Z","0.1.2":"2026-04-02T23:23:57.841Z"},"author":{"name":"banhosdev"},"license":"MIT","homepage":"https://whatsmiau.dev/docs","keywords":["whatsapp","whatsmiau","sdk","api","typescript"],"repository":{"type":"git"},"description":"TypeScript SDK para integracao com a API Whatsmiau.","maintainers":[{"name":"banhosdev","email":"sergiobanhosf@gmail.com"}],"readme":"# @banhosdev/whatsmiau-sdk\n\nSDK TypeScript para integrar com a API da [Whatsmiau](https://whatsmiau.dev), uma API de WhatsApp nao oficial focada em estabilidade e eficiencia.\n\nEste pacote foi modelado com base na documentacao publica da plataforma em [whatsmiau.dev/docs](https://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.\n\n## Instalacao\n\n```bash\nnpm install @banhosdev/whatsmiau-sdk\n```\n\nOu com Bun:\n\n```bash\nbun add @banhosdev/whatsmiau-sdk\n```\n\n## Requisitos\n\n- Node.js `>=18` ou Bun com suporte a `fetch`\n- uma API Key valida gerada no dashboard da Whatsmiau\n- uma ou mais instancias configuradas na plataforma\n\n## Links uteis\n\n- Site: [https://whatsmiau.dev](https://whatsmiau.dev)\n- Documentacao oficial: [https://whatsmiau.dev/docs](https://whatsmiau.dev/docs)\n- Base URL da API: `https://api.whatsmiau.dev`\n\n## Sumario\n\n- [Visao geral](#visao-geral)\n- [Criando o cliente](#criando-o-cliente)\n- [Autenticacao](#autenticacao)\n- [Instancias](#instancias)\n- [Mensagens](#mensagens)\n- [Chat e presenca](#chat-e-presenca)\n- [Webhooks](#webhooks)\n- [Tratamento de erros](#tratamento-de-erros)\n- [Tipos exportados](#tipos-exportados)\n- [Observacoes](#observacoes)\n\n## Visao geral\n\nO SDK e organizado em modulos:\n\n- `client.instances`: criacao, conexao, listagem e exclusao de instancias\n- `client.messages`: envio de texto, midia, audio PTT, listas, botoes e reacoes\n- `client.chat`: presenca, leitura e verificacao de numeros\n- `client.webhooks`: configuracao e consulta de webhooks\n\nTodos os recursos usam um cliente HTTP central com:\n\n- autenticacao por header `apikey`\n- `timeout` configuravel\n- headers customizados\n- `beforeRequest` para observabilidade e logging\n- suporte a `fetch` customizado\n\n## Criando o cliente\n\n### Forma mais simples\n\n```ts\nimport { createWhatsmiauClient } from \"@banhosdev/whatsmiau-sdk\";\n\nconst client = createWhatsmiauClient({\n  apiKey: process.env.WHATSMIAU_API_KEY!,\n});\n```\n\n### Forma explicita\n\n```ts\nimport { WhatsmiauClient } from \"@banhosdev/whatsmiau-sdk\";\n\nconst client = new WhatsmiauClient({\n  apiKey: process.env.WHATSMIAU_API_KEY!,\n  baseUrl: \"https://api.whatsmiau.dev\",\n  timeoutMs: 15_000,\n  headers: {\n    \"x-app-name\": \"banhosdev-app\",\n  },\n  beforeRequest: async ({ url, init }) => {\n    console.log(\"Whatsmiau request:\", init.method, url.toString());\n  },\n});\n```\n\n## Autenticacao\n\nA Whatsmiau usa API Key enviada no header `apikey`. O SDK injeta esse header automaticamente a partir de `apiKey`.\n\n```ts\nconst client = createWhatsmiauClient({\n  apiKey: \"SUA_CHAVE_AQUI\",\n});\n```\n\nPara validar se a chave esta funcional, voce pode listar as instancias:\n\n```ts\nconst response = await client.instances.list();\nconsole.log(response);\n```\n\n## Instancias\n\nCada instancia representa um numero/sessao conectada do WhatsApp.\n\n### Listar instancias\n\nMapeia `GET /evolution/instances`.\n\n```ts\nconst instances = await client.instances.list();\n```\n\n### Criar instancia\n\nMapeia `POST /evolution/instance/create`.\n\n```ts\nconst created = await client.instances.create({\n  instanceName: \"Marketing01\",\n  qrcode: true,\n});\n```\n\nCampos aceitos:\n\n- `instanceName`: nome unico da instancia\n- `qrcode`: se `true`, pede QR code no fluxo de criacao\n- `token`: token customizado da instancia\n\n### Conectar instancia\n\nMapeia `GET /evolution/instance/connect/:id`.\n\n```ts\nconst connection = await client.instances.connect(\"64f1a2b3c4d5e6f7a8b9c0d1\");\n\nconsole.log(connection.data);\n```\n\nUse esse endpoint quando precisar recuperar o QR code ou dados de conexao de uma instancia ja criada.\n\n### Deletar instancia\n\nMapeia `DELETE /evolution/instance/:id`.\n\n```ts\nawait client.instances.delete(\"64f1a2b3c4d5e6f7a8b9c0d1\");\n```\n\n## Mensagens\n\nOs endpoints de mensagem usam o nome ou identificador da instancia na rota.\n\n### Enviar texto\n\nMapeia `POST /message/sendText/:instance`.\n\n```ts\nawait client.messages.sendText(\"Marketing01\", {\n  number: \"551199998888\",\n  text: \"Ola! Sua integracao com a Whatsmiau esta funcionando.\",\n  delay: 1200,\n  linkPreview: true,\n});\n```\n\nTambem suporta:\n\n- `mentionsEveryOne`\n- `mentioned`\n- `quoted`\n\nExemplo respondendo uma mensagem:\n\n```ts\nawait client.messages.sendText(\"Marketing01\", {\n  number: \"551199998888\",\n  text: \"Respondendo sua mensagem anterior\",\n  quoted: {\n    key: {\n      id: \"3EB0XXXXXXXX\",\n    },\n  },\n});\n```\n\n### Enviar midia\n\nMapeia `POST /message/sendMedia/:instance`.\n\n```ts\nawait client.messages.sendMedia(\"Marketing01\", {\n  number: \"551199998888\",\n  mediatype: \"image\",\n  media: \"https://example.com/image.png\",\n  caption: \"Confira a imagem\",\n});\n```\n\nTipos suportados em `mediatype`:\n\n- `image`\n- `video`\n- `document`\n\nExemplo enviando documento:\n\n```ts\nawait client.messages.sendMedia(\"Marketing01\", {\n  number: \"551199998888\",\n  mediatype: \"document\",\n  media: \"https://example.com/catalogo.pdf\",\n  fileName: \"catalogo.pdf\",\n  mimetype: \"application/pdf\",\n});\n```\n\n### Enviar audio PTT\n\nMapeia `POST /message/sendWhatsAppAudio/:instance`.\n\n```ts\nawait client.messages.sendAudio(\"Marketing01\", {\n  number: \"551199998888\",\n  audio: \"https://example.com/voice.mp3\",\n  encoding: true,\n});\n```\n\nEsse formato simula um audio enviado como voz do WhatsApp.\n\n### Enviar lista interativa\n\nMapeia `POST /message/sendList/:instance`.\n\n```ts\nawait client.messages.sendList(\"Marketing01\", {\n  number: \"551199998888\",\n  title: \"Nossos Planos\",\n  description: \"Escolha uma opcao abaixo:\",\n  buttonText: \"Ver opcoes\",\n  footerText: \"Whatsmiau Cloud\",\n  sections: [\n    {\n      title: \"Planos\",\n      rows: [\n        {\n          title: \"Starter\",\n          description: \"R$ 30/mes - 1 instancia\",\n          rowId: \"plan_starter\",\n        },\n        {\n          title: \"Pro\",\n          description: \"R$ 90/mes - 5 instancias\",\n          rowId: \"plan_pro\",\n        },\n      ],\n    },\n  ],\n});\n```\n\n### Enviar botoes interativos\n\nMapeia `POST /message/sendButtons/:instance`.\n\nBotao de resposta rapida:\n\n```ts\nawait client.messages.sendButtons(\"Marketing01\", {\n  number: \"551199998888\",\n  title: \"Confirmar Pedido\",\n  description: \"Deseja confirmar o pedido #1234?\",\n  footer: \"Whatsmiau Cloud\",\n  buttons: [\n    {\n      type: \"reply\",\n      displayText: \"Sim, confirmar\",\n      id: \"confirm_yes\",\n    },\n    {\n      type: \"reply\",\n      displayText: \"Nao, cancelar\",\n      id: \"confirm_no\",\n    },\n  ],\n});\n```\n\nBotao PIX:\n\n```ts\nawait client.messages.sendButtons(\"Marketing01\", {\n  number: \"551199998888\",\n  description: \"Clique para pagar via PIX\",\n  buttons: [\n    {\n      type: \"pix\",\n      displayText: \"Pagar com PIX\",\n      currency: \"BRL\",\n      name: \"Banhos Dev\",\n      keyType: \"email\",\n      key: \"financeiro@banhos.dev\",\n    },\n  ],\n});\n```\n\n### Enviar reacao\n\nMapeia `POST /message/sendReaction/:instance`.\n\n```ts\nawait client.messages.sendReaction(\"Marketing01\", {\n  reaction: \"❤️\",\n  key: {\n    remoteJid: \"5511999998888@s.whatsapp.net\",\n    id: \"3EB0XXXXXXXX\",\n    fromMe: false,\n  },\n});\n```\n\n## Chat e presenca\n\n### Enviar presenca\n\nMapeia `POST /chat/sendPresence/:instance`.\n\n```ts\nawait client.chat.sendPresence(\"Marketing01\", {\n  number: \"551199998888\",\n  presence: \"composing\",\n  type: \"text\",\n  delay: 3000,\n});\n```\n\nValores suportados:\n\n- `presence`: `composing` ou `available`\n- `type`: `text` ou `audio`\n\n### Marcar como lido\n\nMapeia `POST /chat/markMessageAsRead/:instance`.\n\n```ts\nawait client.chat.markAsRead(\"Marketing01\", {\n  readMessages: [\n    {\n      remoteJid: \"5511999998888@s.whatsapp.net\",\n      id: \"3EB0XXXXXXXX\",\n    },\n  ],\n});\n```\n\nEm grupos, informe tambem `sender`.\n\n### Verificar numeros\n\nMapeia `POST /chat/whatsappNumbers/:instance`.\n\n```ts\nconst result = await client.chat.verifyNumbers(\"Marketing01\", {\n  numbers: [\"551199998888\", \"551199997777\"],\n});\n\nconsole.log(result.data);\n```\n\n## Webhooks\n\nOs webhooks permitem receber eventos em tempo real enviados pela Whatsmiau para sua URL HTTP.\n\n### Configurar webhook\n\nMapeia `POST /webhook/set/:instance`.\n\n```ts\nawait client.webhooks.set(\"Marketing01\", {\n  webhook: {\n    enabled: true,\n    url: \"https://meusite.com/webhook\",\n    events: [\"messages.upsert\", \"connection.update\"],\n    headers: {\n      Authorization: \"Bearer meu_token\",\n    },\n    byEvents: true,\n    base64: false,\n  },\n});\n```\n\nCampos suportados em `webhook`:\n\n- `enabled`\n- `url`\n- `events`\n- `headers`\n- `byEvents`\n- `base64`\n\n### Consultar webhook\n\nMapeia `GET /webhook/find/:instance`.\n\n```ts\nconst webhook = await client.webhooks.find(\"Marketing01\");\nconsole.log(webhook.data);\n```\n\n### Tipando o payload do webhook\n\nO SDK exporta o envelope generico `WhatsmiauWebhookEnvelope` e um tipo especifico para `messages.upsert`.\n\n```ts\nimport type {\n  MessagesUpsertWebhook,\n  WhatsmiauWebhookEnvelope,\n} from \"@banhosdev/whatsmiau-sdk\";\n\nfunction handleWebhook(payload: WhatsmiauWebhookEnvelope) {\n  if (payload.event === \"messages.upsert\") {\n    const event = payload as MessagesUpsertWebhook;\n    console.log(event.data.messageType);\n    console.log(event.data.message.conversation);\n  }\n}\n```\n\n### Estrutura do envelope\n\n```ts\ntype WhatsmiauWebhookEnvelope<TData = unknown> = {\n  event: string;\n  instance: string;\n  data: TData;\n  date_time: string;\n  sender?: string;\n  server_url?: string;\n};\n```\n\n### Evento `messages.upsert`\n\nO tipo `MessagesUpsertWebhook` cobre os campos documentados para mensagens recebidas/enviadas, incluindo:\n\n- `key`\n- `pushName`\n- `status`\n- `message`\n- `mediaUrl`\n- `messageType`\n- `messageTimestamp`\n- `instanceId`\n- `contextInfo`\n\nDentro de `message`, o SDK ja tipa as variantes documentadas:\n\n- `conversation`\n- `imageMessage`\n- `videoMessage`\n- `audioMessage`\n- `documentMessage`\n- `reactionMessage`\n- `contactMessage`\n- `listResponseMessage`\n\n## Tratamento de erros\n\nErros HTTP da API sao encapsulados em `WhatsmiauApiError`.\n\n```ts\nimport {\n  WhatsmiauApiError,\n  createWhatsmiauClient,\n} from \"@banhosdev/whatsmiau-sdk\";\n\nconst client = createWhatsmiauClient({\n  apiKey: process.env.WHATSMIAU_API_KEY!,\n});\n\ntry {\n  await client.instances.list();\n} catch (error) {\n  if (error instanceof WhatsmiauApiError) {\n    console.error(error.status, error.statusText, error.body);\n  }\n}\n```\n\n## Tipos exportados\n\nO pacote exporta os principais tipos de request e webhook para uso em apps, backends e middlewares:\n\n- `ApiResponse`\n- `InstanceCreateParams`\n- `InstanceRecord`\n- `InstanceConnectionPayload`\n- `SendTextParams`\n- `MediaMessageParams`\n- `SendAudioParams`\n- `ListMessageParams`\n- `ButtonMessageParams`\n- `ReactionMessageParams`\n- `PresenceParams`\n- `MarkMessagesAsReadParams`\n- `VerifyNumbersParams`\n- `WebhookConfigParams`\n- `WhatsmiauWebhookEnvelope`\n- `MessagesUpsertWebhook`\n\n## Fluxo recomendado\n\nUm fluxo tipico de uso com a API Whatsmiau fica assim:\n\n1. criar o cliente com sua `apiKey`\n2. validar credenciais com `client.instances.list()`\n3. criar uma instancia com `client.instances.create()`\n4. conectar a instancia com `client.instances.connect()`\n5. enviar mensagens com `client.messages.*`\n6. configurar webhooks com `client.webhooks.set()`\n\n## Observacoes\n\n- A documentacao publica da Whatsmiau detalha melhor os contratos de request do que os schemas completos de response.\n- Por isso, o SDK mantem requests fortemente tipados e respostas com flexibilidade quando o payload exato nao e explicitado na documentacao.\n- Os endpoints e tipos foram alinhados com a documentacao publica da versao `v2.1`.\n- Para detalhes operacionais da plataforma, consulte a documentacao oficial em [whatsmiau.dev/docs](https://whatsmiau.dev/docs).\n","readmeFilename":"README.md"}