Pular para o conteúdo

Cliente TypeScript

Um cliente tipado da API, gerado da especificação OpenAPI com openapi-typescript e openapi-fetch: instalação, envio, erros e webhooks.

Ver em Markdown

O cliente TypeScript é gerado da especificação OpenAPI 3.1 a cada mudança da API, sem código escrito à mão: os tipos de cada caminho, parâmetro, corpo, resposta e evento de webhook vêm do openapi-typescript, e as chamadas passam pelo openapi-fetch, uma camada fina sobre o fetch. Não há um método por operação: você chama o caminho da referência (gateway.POST('/connections/{id}/send', …)) e o TypeScript confere o resto.

O que o pacote exporta

ExportaçãoO que é
createGatewayClient(options)Cria o cliente. options.baseUrl é o endereço da API e options.apiKey a sua chave; as demais opções do openapi-fetch (headers, fetch…) também são aceitas
GatewayClientO tipo do cliente (Client<paths> do openapi-fetch)
paths, operations, components, webhooksOs tipos gerados da especificação
SchemasOs esquemas nomeados: os eventos de webhook (MessageIncomingEvent…) e o corpo de erro (ErrorResponse)
WebhookEventO envelope de todo evento de webhook (WebhookEventEnvelope)
SendMessageRequestO corpo de POST /connections/{id}/send
QueuedMessageA resposta 202 do envio

O pacote exige Node.js 18 ou mais novo (o fetch nativo) e depende só do openapi-fetch 0.17.0.

1Instale

Com o pacote recebido do suporte, instale o arquivo direto (o nome segue whatsapp-gateway-client-<versão>.tgz):

bashPacote pronto
npm install ./whatsapp-gateway-client-1.0.0.tgz

Para gerar você mesmo, instale o openapi-fetch e gere os tipos a partir da especificação publicada nesta documentação:

bashGerar os tipos
npm install [email protected]
npm install --save-dev [email protected] typescript
npx openapi-typescript https://apiwpp.com/docs/openapi.json -o src/gateway/schema.ts

Depois, crie ao lado dos tipos o mesmo arquivo que o pacote traz. Ele é o único código do cliente que não é gerado:

tssrc/gateway/index.ts
import createClient, { type Client, type ClientOptions } from 'openapi-fetch';

import type { components, operations, paths, webhooks } from './schema.js';

export type { components, operations, paths, webhooks };

/** Todos os esquemas nomeados: os eventos de webhook e o corpo de erro */
export type Schemas = components['schemas'];

/** O corpo de todo POST de webhook; `data` é o esquema do `type` */
export type WebhookEvent = Schemas['WebhookEventEnvelope'];

/** O corpo de POST /connections/{id}/send */
export type SendMessageRequest = NonNullable<
  paths['/connections/{id}/send']['post']['requestBody']
>['content']['application/json'];

/** A resposta 202 de POST /connections/{id}/send */
export type QueuedMessage = paths['/connections/{id}/send']['post']['responses'][202]['content']['application/json'];

export interface GatewayClientOptions extends Omit<ClientOptions, 'baseUrl'> {
  baseUrl: string;
  /** Uma chave de API (wag_live_…), enviada como Authorization: Bearer */
  apiKey: string;
}

export type GatewayClient = Client<paths>;

export function createGatewayClient({ apiKey, ...options }: GatewayClientOptions): GatewayClient {
  const client = createClient<paths>(options);
  client.use({
    onRequest({ request }) {
      request.headers.set('Authorization', `Bearer ${apiKey}`);
      return request;
    },
  });
  return client;
}

Nos exemplos abaixo, troque 'whatsapp-gateway-client' por './gateway/index.js' se você gerou o cliente. Quando a API mudar, rode o openapi-typescript de novo: um campo que mudou vira erro de compilação no seu código, não uma surpresa em produção.

2Crie o cliente

tsgateway.ts
import { createGatewayClient } from 'whatsapp-gateway-client';

export const gateway = createGatewayClient({
  baseUrl: 'https://api.apiwpp.com',
  apiKey: process.env.WHATSAPP_API_KEY!,
});

Toda requisição sai com Authorization: Bearer <chave>. Guarde a chave num cofre de segredos ou numa variável de ambiente, nunca no código, e dê a ela só os escopos das operações que o seu sistema chama (veja Autenticação).

Para conferir a chave, chame GET /me:

tsVer na referência
const { data, error, response } = await gateway.GET('/me');
if (error) throw new Error(`${response.status}: ${error.error}`);

console.log(data.kind); // "apiKey"

3Envie uma mensagem

Os parâmetros de caminho vão em params.path, os de consulta em params.query e o corpo em body, todos tipados pela especificação. Um campo que não existe, ou um to esquecido, não compila.

tsVer na referência
import { gateway } from './gateway';

const connectionId = process.env.WHATSAPP_CONNECTION_ID!;

const { data, error, response } = await gateway.POST('/connections/{id}/send', {
  params: { path: { id: connectionId } },
  body: {
    to: '5511988887777',
    message: 'Olá! Seu pedido 1234 saiu para entrega.',
    clientRef: 'pedido-1234',
  },
});

if (error) throw new Error(`${response.status}: ${error.error}`);

if ('duplicate' in data && data.duplicate) {
  // 200: um envio anterior com o mesmo clientRef já tinha enfileirado esta mensagem
  console.log('Já estava na fila:', data.jobId);
} else {
  // 202: enfileirada agora
  console.log('Na fila:', data.jobId, 'posição', data.position);
}

A resposta 202 traz o jobId, o scheduledAt (milissegundos unix do envio previsto) e a position na fila do número. Repetir a mesma requisição com o mesmo clientRef responde 200 com duplicate: true e o job original, sem enfileirar de novo: é assim que um envio pode ser repetido com segurança depois de uma falha de rede (veja Idempotência). O guia de envio mostra mídia, localização e templates.

Um GET com parâmetros de consulta, como o registro de mensagens:

tsVer na referência
const { data, error } = await gateway.GET('/messages', {
  params: { query: { direction: 'out', status: 'failed', limit: 20 } },
});

4Trate os erros

O openapi-fetch não lança exceção por status HTTP: toda chamada devolve data (nas respostas 2xx) ou error (nas demais), mais o response original. O error é o corpo de erro da API (Schemas['ErrorResponse']): error sempre, e às vezes message, statusCode, code e feature. Decida pelo response.status e pelo code, nunca pelo texto de error, que é para pessoas e pode mudar. Só uma falha de rede (ou o seu AbortSignal) lança exceção.

tsTratar os erros
const { data, error, response } = await gateway.POST('/connections/{id}/send', {
  params: { path: { id: connectionId } },
  body: { to: '5511988887777', message: 'Olá!', clientRef: 'pedido-1234' },
});

if (error) {
  switch (response.status) {
    case 400: // corpo inválido, destinatário inválido ou conexão que não está aberta
      throw new Error(`Requisição recusada: ${error.message ?? error.error}`);
    case 401: // chave ausente, desconhecida, revogada ou expirada
    case 403: // falta um escopo, ou o plano não inclui o recurso (code: plan_feature_required)
      throw new Error(`Credencial: ${error.error}`);
    case 402: // code: subscription_inactive
      throw new Error('A assinatura da organização não está em dia');
    case 429:
    case 503: {
      // Espere o Retry-After e repita com o mesmo clientRef: não duplica
      const seconds = Number(response.headers.get('Retry-After') ?? 60);
      throw new RetryLater(seconds);
    }
    default:
      throw new Error(`${response.status}: ${error.error}`);
  }
}

RetryLater aqui é uma classe sua, que agenda a nova tentativa. No 429 de POST /connections/{id}/send, o cabeçalho X-Usage-Percent diz quanto da cota do plano já foi usado; a tabela completa de status e códigos está em Códigos de erro, e os cabeçalhos em Cabeçalhos.

5Receba os webhooks com tipos

Os eventos de webhook estão na mesma especificação, e o pacote exporta os tipos deles: WebhookEvent é o envelope, e Schemas['MessageIncomingEvent'], Schemas['MessageDeliveryEvent'] e os demais são o data de cada tipo. Verifique a assinatura sobre o corpo bruto antes de converter o JSON: o exemplo importa de ./webhook-signature a função isSigned do guia Webhooks e assinatura, exportada.

tsReceber eventos
import express from 'express';
import type { Schemas, WebhookEvent } from 'whatsapp-gateway-client';

import { isSigned } from './webhook-signature';

type Incoming = WebhookEvent & { type: 'message.incoming'; data: Schemas['MessageIncomingEvent'] };
type Delivery = WebhookEvent & { type: 'message.delivery'; data: Schemas['MessageDeliveryEvent'] };

const app = express();

app.post('/whatsapp/events', express.raw({ type: 'application/json' }), (req, res) => {
  if (!isSigned(req.body, req.get('X-Sales-Timestamp'), req.get('X-Sales-Signature'))) {
    return res.sendStatus(401);
  }
  // Responda 2xx logo e processe fora da requisição
  res.sendStatus(204);

  const event = JSON.parse(req.body.toString('utf8')) as { type: string };
  switch (event.type) {
    case 'message.incoming': {
      const { data } = event as Incoming;
      console.log(data.phone ?? data.jid, 'escreveu:', data.body);
      break;
    }
    case 'message.delivery': {
      const { data } = event as Delivery;
      console.log(data.messageId, data.status);
      break;
    }
    default:
      // ping e tipos novos: ignore o que você não conhece
      break;
  }
});

app.listen(3000);

A entrega é pelo menos uma vez: o mesmo evento pode chegar de novo, então aplique cada um de forma idempotente (por data.messageId, quando houver). A lista dos eventos e dos campos de cada um está em Webhooks.

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026