Pular para o conteúdo
apiwpp
Integração

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:

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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.