Cliente TypeScript da API de WhatsApp: tipos gerados da OpenAPI 3.1
Chamadas tipadas à API de WhatsApp com openapi-fetch e tipos gerados da especificação OpenAPI 3.1: envio, erros e eventos de webhook no TypeScript.
Atualizado em
A apiwpp descreve a API inteira numa especificação OpenAPI 3.1 pública, em português e em inglês. É dela que sai o cliente TypeScript: os tipos são gerados com o openapi-typescript e as chamadas passam pelo openapi-fetch, uma camada fina sobre o fetch. Nada é escrito à mão, então o cliente acompanha a API sem ficar desatualizado. Se você errar o nome de um campo ou esquecer um parâmetro, o compilador avisa antes de a requisição sair.
Como obter o cliente
Os clientes TypeScript e PHP são gerados da especificação a cada mudança da API, mas ainda não estão publicados em registros de pacotes como o npm. Há dois caminhos:
- Pedir o pacote pronto pelo suporte, em contato. Ele traz uma função que já envia a chave em cada requisição e exporta os tipos das rotas e dos eventos de webhook.
- Gerar os tipos no seu projeto, com um comando, e usar o
openapi-fetchdireto. É o que esta página mostra, porque funciona hoje sem depender de ninguém.
Nos dois casos, o resultado é o mesmo: os tipos vêm da mesma especificação que a referência interativa usa.
Gerar os tipos da especificação
npx openapi-typescript https://docs.apiwpp.com/openapi.json -o src/apiwpp.d.ts
npm install openapi-fetch
O arquivo gerado exporta paths (cada rota com seus parâmetros, corpos e respostas), components (os schemas nomeados, entre eles os eventos de webhook) e webhooks. Vale guardar o comando num script do package.json, como "apiwpp:types", para regenerar quando quiser.
Criar o cliente com a chave de API
A chave vai no cabeçalho Authorization: Bearer. Crie o cliente uma vez, num módulo do servidor, e reutilize:
// src/whatsapp.ts
import createClient from 'openapi-fetch'
import type { components, paths } from './apiwpp'
export type Schemas = components['schemas']
export const apiwpp = createClient<paths>({
baseUrl: 'https://api.apiwpp.com',
headers: { Authorization: `Bearer ${process.env.APIWPP_KEY}` },
})
Use uma chave com escopo, como messages:send para quem só envia. Nunca coloque a chave num código que roda no navegador: o cliente é para o seu backend, uma função serverless ou um worker.
Envio tipado
POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt (milissegundos unix) e position. Com o cliente, o caminho é autocompletado, o id vai em params.path e o corpo é conferido contra a especificação:
import { apiwpp } from './whatsapp'
export async function sendText(connectionId: string, to: string, message: string, clientRef: string) {
const { data, error, response } = await apiwpp.POST('/connections/{id}/send', {
params: { path: { id: connectionId } },
body: { to, message, clientRef },
})
if (error) {
if (response.status === 429) {
const retryAfter = Number(response.headers.get('retry-after') ?? 60)
return { queued: false as const, retryAfter } // schedule a new attempt in your own queue
}
throw new Error(`apiwpp ${response.status}: ${error.error}`)
}
// 202 queued, or 200 with duplicate: true when this clientRef was already accepted
return { queued: true as const, jobId: data.jobId, scheduledAt: data.scheduledAt }
}
O error segue o modelo de erro da API, com o campo error (como new_recipient_cap_reached). O 429 com esse código é o teto de destinatários novos do número: nada entra na fila e o cabeçalho Retry-After diz quanto esperar. A proteção inteira está na página da fila com ritmo anti-bloqueio.
O clientRef torna a chamada segura para repetir: uma repetição com o mesmo valor, na mesma conexão, devolve o job original sem enfileirar de novo. Derive-o do que o envio representa, como pedido-1234-envio, e nunca de um valor aleatório.
Os demais conteúdos são checados do mesmo jeito. Um media sem url ou um type fora da lista (image, video, audio, document, sticker) não compila:
await apiwpp.POST('/connections/{id}/send', {
params: { path: { id: connectionId } },
body: {
to: '5511988887777',
template: 'confirmacao_pedido',
variables: { nome: 'Ana', pedido: '1234' },
clientRef: 'pedido-1234-confirmacao',
},
})
Extrair os tipos de cada rota
Para tipar as suas próprias funções, tire os tipos direto de paths:
import type { paths } from './apiwpp'
type Send = paths['/connections/{id}/send']['post']
export type SendBody = NonNullable<Send['requestBody']>['content']['application/json']
export type QueuedMessage = Send['responses'][202]['content']['application/json']
Assim, um formulário do seu painel ou uma fila interna trabalham com o mesmo formato que a API aceita, e uma mudança na especificação aparece como erro de compilação no lugar certo.
Tipos dos eventos de webhook
Os eventos também estão na especificação. O envelope é WebhookEventEnvelope (type, connectionId, tenantId, externalId, timestamp e data), e cada tipo de evento tem o seu schema, como MessageIncomingEvent e MessageDeliveryEvent:
import type { Schemas } from './whatsapp'
export function handleEvent(event: Schemas['WebhookEventEnvelope']) {
switch (event.type) {
case 'message.incoming': {
const data = event.data as Schemas['MessageIncomingEvent']
return saveIncoming(data.from, data.body)
}
case 'message.delivery': {
const data = event.data as Schemas['MessageDeliveryEvent']
return updateStatus(data.clientRef, data.status)
}
default:
return // new event types: ignore, never reject
}
}
Os tipos descrevem o formato, mas não provam a origem. Confira a assinatura HMAC-SHA256 do corpo bruto antes de fazer o JSON.parse, como mostra o exemplo com Express da página de Node.js, que funciona igual em TypeScript. A lista completa de eventos está em webhooks assinados.
Quando regenerar
A especificação só cresce: um campo novo ou um tipo de evento novo não quebra quem já integrou, e o seu código deve ignorar os tipos que não conhece. Regenere os tipos quando for usar um recurso novo, ou rode o script no CI para saber quando algo mudou. Para ver o envio com fetch puro, passo a passo, leia o tutorial enviar mensagem de WhatsApp com Node.js, e para o panorama dos clientes, a página de OpenAPI e clientes gerados.
Perguntas frequentes
O cliente TypeScript está no npm?
Ainda não. Os clientes são gerados da especificação a cada mudança da API, mas não estão publicados em registros de pacotes. Enquanto isso, peça o pacote pronto pelo suporte ou gere os tipos no seu projeto com o openapi-typescript, como mostra esta página.
Preciso do cliente para usar a API em TypeScript?
Não. A API é REST com JSON, e um fetch com o cabeçalho Authorization basta. O cliente só acrescenta os tipos: autocompletar, checagem do corpo e das respostas, e erros de compilação quando algo muda.
Posso chamar a API direto do navegador?
Não é recomendado. A chave de API daria acesso ao projeto a qualquer pessoa que abrisse o código da página. Chame a API do seu backend, de uma função serverless ou de um worker, e exponha ao navegador só as rotas do seu sistema.
Os tipos cobrem os eventos de webhook?
Sim. A especificação descreve o envelope e o data de cada evento, e o arquivo gerado os exporta em components['schemas']. Use-os depois de verificar a assinatura da entrega.
Outras integrações
Todos: Integrações →Envie mensagens com o fetch nativo do Node.js, sem dependências, e receba os eventos num endpoint Express que verifica a assinatura HMAC-SHA256 de cada entrega.
Envie mensagens com curl ou Guzzle, use o cliente PHP gerado da especificação OpenAPI 3.1 e receba os eventos num script que confere a assinatura HMAC-SHA256 com hash_hmac e hash_equals.
Envie mensagens de WhatsApp a partir de Jobs do Laravel com o Http facade e clientRef, receba os eventos numa rota protegida por um middleware de assinatura HMAC e processe tudo na fila, sem duplicar.