Cliente TypeScript
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 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çã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.
1Instale
Com o pacote recebido do suporte, instale o arquivo direto (o nome segue whatsapp-gateway-client-<versão>.tgz):
npm install ./whatsapp-gateway-client-1.0.0.tgzPara gerar você mesmo, instale o openapi-fetch e gere os tipos a partir da especificação publicada nesta documentação:
npm install [email protected]
npm install --save-dev [email protected] typescript
npx openapi-typescript https://apiwpp.com/docs/openapi.json -o src/gateway/schema.tsDepois, crie ao lado dos tipos o mesmo arquivo que o pacote traz. Ele é o único código do cliente que não é gerado:
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
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:
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.
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:
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.
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.
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
- Enviar mensagens: texto, mídia, localização, templates e a fila do número.
- Webhooks e assinatura: o endpoint, a assinatura e as novas tentativas.
- Visão geral da API: todas as operações que o cliente pode chamar.
- Cliente PHP: o mesmo, gerado para PHP.