# Cliente TypeScript

Fonte: https://apiwpp.com/docs/clientes/typescript
Seção: Clientes
Atualizado em: 2026-09-29

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

O cliente TypeScript é gerado da [especificação OpenAPI 3.1](https://apiwpp.com/docs/api) 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](https://openapi-ts.dev/), e as chamadas passam pelo [openapi-fetch](https://openapi-ts.dev/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.

> **Ainda não está no npm**
>
> O pacote `whatsapp-gateway-client` ainda não foi publicado em nenhum registro de pacotes. Há dois caminhos: pedir o pacote pronto (um arquivo `.tgz`) pelo suporte, ou gerar os tipos você mesmo a partir da especificação, como no passo 1. O resultado é o mesmo código.

## O que o pacote exporta

| Exportação | O 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 |
| `GatewayClient` | O tipo do cliente (`Client<paths>` do openapi-fetch) |
| `paths`, `operations`, `components`, `webhooks` | Os tipos gerados da especificação |
| `Schemas` | Os esquemas nomeados: os eventos de webhook (`MessageIncomingEvent`…) e o corpo de erro (`ErrorResponse`) |
| `WebhookEvent` | O envelope de todo evento de webhook (`WebhookEventEnvelope`) |
| `SendMessageRequest` | O corpo de `POST /connections/{id}/send` |
| `QueuedMessage` | A 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`.

## 1. Instale

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

**Pacote pronto**

```bash
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](https://apiwpp.com/docs/openapi.json):

**Gerar os tipos**

```bash
npm install openapi-fetch@0.17.0
npm install --save-dev openapi-typescript@7.13.0 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:

**src/gateway/index.ts**

```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.

## 2. Crie o cliente

**gateway.ts**

```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](https://apiwpp.com/docs/referencia/escopos) das operações que o seu sistema chama (veja [Autenticação](https://apiwpp.com/docs/autenticacao)).

Para conferir a chave, chame [`GET /me`](https://apiwpp.com/docs/api/conta/quem-esta-chamando):

**Confira a chave**

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

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

## 3. Envie 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.

**Enviar mensagem**

```ts
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](https://apiwpp.com/docs/guias/idempotencia)). O [guia de envio](https://apiwpp.com/docs/guias/enviar-mensagens) mostra mídia, localização e templates.

Um `GET` com parâmetros de consulta, como o [registro de mensagens](https://apiwpp.com/docs/api/registros/listar-mensagens):

**Mensagens que falharam**

```ts
const { data, error } = await gateway.GET('/messages', {
  params: { query: { direction: 'out', status: 'failed', limit: 20 } },
});
```

## 4. Trate 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](https://apiwpp.com/docs/guias/erros) 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.

**Tratar os erros**

```ts
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](https://apiwpp.com/docs/referencia/codigos-de-erro), e os cabeçalhos em [Cabeçalhos](https://apiwpp.com/docs/referencia/cabecalhos).

## 5. Receba 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](https://apiwpp.com/docs/guias/webhooks-e-assinatura#verifique-a-assinatura), exportada.

**Receber eventos**

```ts
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);
```

> **O ping não está nos tipos**
>
> O evento [`ping`](https://apiwpp.com/docs/webhooks/ping), enviado só pelo teste do endpoint, não faz parte da especificação: ele não está no `type` de `WebhookEvent`, e o seu `connectionId` e `tenantId` são `null`. Por isso o exemplo lê `type` antes de assumir o envelope completo. Ignore os tipos que você não conhece e responda `2xx`: a API pode ganhar eventos novos.

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](https://apiwpp.com/docs/webhooks).

## Próximos passos

- [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens): texto, mídia, localização, templates e a fila do número.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): o endpoint, a assinatura e as novas tentativas.
- [Visão geral da API](https://apiwpp.com/docs/api): todas as operações que o cliente pode chamar.
- [Cliente PHP](https://apiwpp.com/docs/clientes/php): o mesmo, gerado para PHP.
