---
title: "SDK JavaScript/TypeScript para a API do WhatsApp"
description: "O SDK oficial da WAME em Node.js e TypeScript: envio tipado com autocompletar, os três canais da Meta na mesma chamada e o webhook no envelope padrão. Instalação, primeiro envio e o handler que serve WhatsApp, Instagram e Messenger."
url: "https://api-wa.me/blog/sdk-javascript-typescript-whatsapp"
language: "pt-BR"
og:type: "article"
og:site_name: "WAME API"
---

[Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/SDK JavaScript e TypeScript da WAME: WhatsApp tipado, nos três canais

Raphael Serafim· Publicado em 10 de setembro de 2026· 9 min de leitura

Compartilhar

# SDK JavaScript e TypeScript da WAME: WhatsApp tipado, nos três canais

O SDK oficial da WAME em Node.js e TypeScript: envio tipado com autocompletar, os três canais da Meta na mesma chamada e o webhook no envelope padrão. Instalação, primeiro envio e o handler que serve WhatsApp, Instagram e Messenger.

Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/sdk-javascript-typescript-whatsapp.md)

**Se o seu sistema é Node, o SDK da WAME tipa a integração inteira** — os três canais da Meta, o envio, a instância e o webhook. Este guia vai do `npm install` até o handler recebendo mensagem.

## Instalação

```bash
npm install @raphaelvserafim/client-api-whatsapp
```

```ts
import { Wame, TypeMessage } from '@raphaelvserafim/client-api-whatsapp';

const wa = new Wame({
  server: 'https://us.api-wa.me',
  key: process.env.WAME_KEY!,
});
```

Os tipos vêm no pacote. Não há `@types` separado para instalar.

## Primeiro envio

```ts
const to = '5566996852025';   // internacional, só dígitos

await wa.message.send({
  type: TypeMessage.TEXT,
  body: { to, text: 'Seu pedido #1042 saiu para entrega 🚚' },
});
```

O `TypeMessage` é um enum, e é ele que faz o trabalho pesado no editor: o autocompletar lista os tipos disponíveis, e o corpo esperado muda conforme o tipo escolhido.

```ts
// o compilador recusa: mensagem de texto não tem `url`
await wa.message.send({
  type: TypeMessage.TEXT,
  body: { to, url: 'https://exemplo.com/foto.jpg' },
});
```

Esse erro, num projeto sem tipos, seria uma resposta 400 em produção às três da manhã.

## Mídia

```ts
await wa.message.send({
  type: TypeMessage.IMAGE,
  body: { to, url: 'https://exemplo.com/nota.jpg', caption: 'Sua NF-e' },
});

await wa.message.send({
  type: TypeMessage.AUDIO,
  body: { to, url: 'https://exemplo.com/audio.mp3' },
});
```

## Os três canais

```ts
await wa.message.send({
  type: TypeMessage.TEXT,
  body: { to, text: 'Oi', provider: 'instagram' },
});
```

Um campo. Sem `provider`, vai no WhatsApp; com `instagram` ou `messenger`, vai no outro canal — [mesma instância, mesma chave, mesmo webhook](https://api-wa.me/blog/api-instagram-messenger-mesma-api-whatsapp).

## Instância e webhook

```ts
// Conectar (API não oficial)
const qr = await wa.instance.connect();
const code = await wa.instance.pairingCode('5566996852025');

// Estado
const info = await wa.instance.info();

// Operação
await wa.instance.logout();
await wa.instance.restart();
await wa.instance.resync();
```

Configurar para onde os eventos vão:

```ts
await wa.instance.updateWebhook({
  allowWebhook: true,
  allowNumber: 'all',
  webhookMessage: 'https://seusistema.com/webhook/wame',
  webhookFormat: 'meta',   // envelope da Cloud API — o mesmo p/ os 3 canais
});

const stats = await wa.instance.webhookStatistics();
```

O `webhookStatistics()` vale conhecer: quando o webhook "para de funcionar", ele mostra se as entregas estão saindo e falhando ou se nem estão sendo tentadas — o que decide em que lado procurar. É o primeiro passo depois do [teste com webhook.site](https://api-wa.me/blog/webhook-whatsapp-nao-chega-como-testar).

## O handler que serve os três canais

```ts
import express from 'express';

type EventoWame = {
  provider: 'whatsapp' | 'instagram' | 'messenger';
  entry: Array<{
    changes: Array<{
      value: {
        messages?: Array<{
          from: string;
          id: string;
          type: string;
          text?: { body: string };
        }>;
        statuses?: Array<{ id: string; status: string }>;
      };
    }>;
  }>;
};

const app = express();
app.use(express.json());

app.post('/webhook/wame', (req, res) => {
  res.sendStatus(200);                     // primeiro isto, sempre
  processar(req.body as EventoWame).catch(console.error);
});

async function processar(evento: EventoWame) {
  const value = evento.entry?.[0]?.changes?.[0]?.value;

  // `statuses` é entrega/leitura, não mensagem nova.
  const msg = value?.messages?.[0];
  if (!msg || msg.type !== 'text') return;

  await registrar({
    canal: evento.provider,
    de: msg.from,
    texto: msg.text!.body,
    messageId: msg.id,
  });
}
```

Um handler. Três canais. O único campo que varia é `provider`.

## Em Next.js e serverless

Só no servidor:

```ts
// app/api/webhook/wame/route.ts
export async function POST(req: Request) {
  const evento = await req.json();
  after(() => processar(evento));   // responde já, processa depois
  return Response.json({ ok: true });
}
```

**Nunca chame o SDK a partir do cliente.** A chave da instância iria para o bundle, e qualquer visitante poderia enviar mensagem pelo seu número. Server action, route handler ou função serverless — nunca componente de cliente.

Em serverless há uma segunda armadilha: se você responde e a função encerra, o processamento em segundo plano morre junto. Use o mecanismo da plataforma para trabalho pós-resposta (`after` no Next, `waitUntil` em edge runtimes) ou empurre para uma fila.

## Tratamento de erro

```ts
try {
  await wa.message.send({ type: TypeMessage.TEXT, body: { to, text } });
} catch (e) {
  // Número sem WhatsApp, instância desconectada, limite atingido.
  // O erro traz o código; trate cada caso, não engula tudo num catch mudo.
  console.error('falha ao enviar para', to, e);
  await enfileirarParaNovaTentativa({ to, text });
}
```

Vale conferir antes de mandar, quando a lista veio de cadastro do cliente:

```ts
const existe = await wa.contact.checkNumber(to);
if (!existe) return marcarInvalido(to);
```

Isso é o que separa uma lista que entrega de uma lista que queima reputação — assunto de [higiene de lista e opt-out](https://api-wa.me/blog/lista-contatos-optin-optout-whatsapp).

## Conclusão

O ganho do SDK tipado não é escrever menos: é o compilador recusando o payload errado antes do deploy. Com três canais no mesmo contrato, isso vale três vezes.

Se você trabalha em PHP, o [SDK PHP](https://api-wa.me/blog/sdk-php-whatsapp-instagram-messenger) cobre o mesmo terreno. Se vai colocar isso em produção, [webhook em produção](https://api-wa.me/blog/webhook-producao-assinatura-retry-idempotencia) trata da parte que só aparece com volume.

Referência completa em [docs/sdk/ts](https://api-wa.me/docs/sdk/ts).

### Pronto para automatizar seu WhatsApp?

Crie sua conta gratuita e comece a enviar mensagens pela API em minutos.

[Começar grátis](https://portal.api-wa.me/sign-up)

## Perguntas frequentes

Como instalar o SDK JavaScript da WAME?+

npm install @raphaelvserafim/client-api-whatsapp. O pacote já inclui as definições de tipo, então funciona em JavaScript puro e em TypeScript sem instalar @types separado.

O SDK funciona com TypeScript?+

Sim, e é onde ele rende mais. Os tipos de mensagem são um enum (TypeMessage) e o corpo de cada tipo é tipado, então o editor mostra os campos válidos e o compilador acusa erro se você mandar url numa mensagem de texto.

Dá para usar o SDK em Next.js ou em serverless?+

Sim, desde que a chamada aconteça no servidor: route handler, server action ou função serverless. Nunca no cliente — a chave da instância ficaria exposta no bundle e qualquer pessoa poderia enviar mensagens em nome do seu número.

Como enviar no Instagram e no Messenger pelo SDK?+

É o mesmo método send, com o campo provider no corpo da mensagem. WhatsApp é o padrão; informar instagram ou messenger direciona a mesma chamada ao outro canal, porque a instância cobre os três.

O SDK cobre criação de instância?+

Sim. O objeto instance expõe conexão por QR Code e por pairing code, informações, logout, restart, resync e configuração de webhook — o suficiente para provisionar e operar contas sem ninguém abrir um painel.

## Continue lendo

[### Baileys (WhatsApp): o que é e quando usar uma API pronta

Entenda o que é o Baileys, a biblioteca open-source que conecta ao WhatsApp Web e serve de base para muitas APIs não oficiais. Veja prós, contras e quando usar uma API pronta em vez de construir do zero.](https://api-wa.me/blog/baileys-whatsapp)[### Como criar um chatbot de IA com a API da OpenAI para responder no WhatsApp

Um webhook, uma chamada à API da OpenAI e uma resposta pela WAME API: o código completo de um chatbot de IA que atende no WhatsApp, Instagram e Messenger. Com memória por contato, controle de custo e o que fazer quando a IA não deve responder.](https://api-wa.me/blog/chatbot-ia-openai-whatsapp)[### Cobrança por Pix dentro do WhatsApp pela API: como enviar e o que muda na conversão

Mandar o código Pix no WhatsApp resolve o pior ponto da cobrança digital: o cliente não precisa sair do app. Como enviar a cobrança pela API, tratar a confirmação e evitar os erros que transformam a facilidade em suporte.](https://api-wa.me/blog/cobrar-pix-whatsapp-api)

[Voltar ao blog](https://api-wa.me/blog)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "WAME API",
  "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram e Messenger",
  "url": "https://api-wa.me",
  "inLanguage": "pt-BR",
  "publisher": {
    "@id": "https://api-wa.me/#organization",
    "@type": "Organization",
    "name": "WAME API",
    "url": "https://api-wa.me"
  }
}
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://api-wa.me/#organization",
  "name": "WAME API",
  "alternateName": [
    "WAME",
    "Wame API",
    "wame.api.br",
    "api-wa.me"
  ],
  "url": "https://api-wa.me",
  "logo": {
    "@type": "ImageObject",
    "url": "https://api-wa.me/images/web-app-manifest-512x512.png",
    "width": 512,
    "height": 512
  },
  "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.",
  "identifier": {
    "@type": "PropertyValue",
    "propertyID": "INPI-BR",
    "name": "Pedido de registro de marca (INPI, classe NCL 42)",
    "value": "944724159"
  },
  "foundingDate": "2017",
  "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram e Messenger numa instância só. Desde 2017.",
  "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.",
  "knowsAbout": [
    "WhatsApp Cloud API oficial (Meta)",
    "API oficial de Instagram (Direct)",
    "API oficial de Messenger",
    "API multicanal Meta",
    "Meta Business Partner",
    "WhatsApp API",
    "API não oficial de WhatsApp",
    "automação de WhatsApp",
    "números virtuais",
    "webhooks"
  ],
  "sameAs": [
    "https://github.com/wame-api",
    "https://www.linkedin.com/company/wameapi",
    "https://www.instagram.com/wame.api/",
    "https://www.youtube.com/@wameapi"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer support",
    "url": "https://api-wa.me/contact",
    "availableLanguage": [
      "Portuguese"
    ]
  }
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "SDK JavaScript e TypeScript da WAME: WhatsApp tipado, nos três canais",
  "description": "O SDK oficial da WAME em Node.js e TypeScript: envio tipado com autocompletar, os três canais da Meta na mesma chamada e o webhook no envelope padrão. Instalação, primeiro envio e o handler que serve WhatsApp, Instagram e Messenger.",
  "image": "https://api-wa.me/blog/sdk-javascript-typescript-whatsapp/opengraph-image",
  "datePublished": "2026-09-10",
  "dateModified": "2026-09-10",
  "author": {
    "@type": "Person",
    "name": "Raphael Serafim",
    "url": "https://github.com/raphaelvserafim",
    "sameAs": [
      "https://github.com/raphaelvserafim"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "api-wa.me",
    "logo": {
      "@type": "ImageObject",
      "url": "https://api-wa.me/images/screenshot.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://api-wa.me/blog/sdk-javascript-typescript-whatsapp"
  },
  "keywords": "sdk whatsapp javascript, api whatsapp node js, whatsapp typescript, npm whatsapp api, enviar whatsapp node, sdk whatsapp nodejs, biblioteca whatsapp node",
  "inLanguage": "pt-BR"
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://api-wa.me"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog da API do WhatsApp",
      "item": "https://api-wa.me/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "SDK JavaScript e TypeScript da WAME: WhatsApp tipado, nos três canais",
      "item": "https://api-wa.me/blog/sdk-javascript-typescript-whatsapp"
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Como instalar o SDK JavaScript da WAME?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "npm install @raphaelvserafim/client-api-whatsapp. O pacote já inclui as definições de tipo, então funciona em JavaScript puro e em TypeScript sem instalar @types separado."
      }
    },
    {
      "@type": "Question",
      "name": "O SDK funciona com TypeScript?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Sim, e é onde ele rende mais. Os tipos de mensagem são um enum (TypeMessage) e o corpo de cada tipo é tipado, então o editor mostra os campos válidos e o compilador acusa erro se você mandar url numa mensagem de texto."
      }
    },
    {
      "@type": "Question",
      "name": "Dá para usar o SDK em Next.js ou em serverless?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Sim, desde que a chamada aconteça no servidor: route handler, server action ou função serverless. Nunca no cliente — a chave da instância ficaria exposta no bundle e qualquer pessoa poderia enviar mensagens em nome do seu número."
      }
    },
    {
      "@type": "Question",
      "name": "Como enviar no Instagram e no Messenger pelo SDK?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "É o mesmo método send, com o campo provider no corpo da mensagem. WhatsApp é o padrão; informar instagram ou messenger direciona a mesma chamada ao outro canal, porque a instância cobre os três."
      }
    },
    {
      "@type": "Question",
      "name": "O SDK cobre criação de instância?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Sim. O objeto instance expõe conexão por QR Code e por pairing code, informações, logout, restart, resync e configuração de webhook — o suficiente para provisionar e operar contas sem ninguém abrir um painel."
      }
    }
  ]
}
```