Pular para o conteúdo
apiwpp
Caso de uso

WhatsApp para SaaS e CRMs: cada cliente conecta o próprio número

API de WhatsApp para CRM e SaaS: o cliente pareia o número dentro do seu produto, as conversas chegam por webhook e o custo é por número conectado.

Atualizado em

Os clientes do seu SaaS já conversam com os clientes deles pelo WhatsApp, só que essas conversas vivem num celular, fora do CRM, fora do histórico e fora de qualquer relatório. O pedido que chega ao time de produto é sempre o mesmo: "dá para conectar o nosso WhatsApp aqui dentro?".

Com a apiwpp, dá. Cada cliente seu pareia o próprio número por um QR code que o seu produto mostra, as mensagens chegam ao seu servidor por webhook e o seu sistema sabe a qual conta cada evento pertence. Você não hospeda sessões do WhatsApp, não mantém proxies e não escreve uma fila de envio.

Como o modelo da apiwpp encaixa num SaaS

A apiwpp tem três níveis, e cada um tem um lugar claro no seu produto:

Na apiwppNo seu SaaS
OrganizaçãoA sua empresa, com uma assinatura e uma fatura para todos os números
Projeto (tenant na API)O seu sistema em produção, com webhook e chaves de API próprios
ConexãoO número de WhatsApp de um cliente seu
externalIdO id desse cliente no seu banco de dados

O desenho mais comum é um projeto para o SaaS e uma conexão para cada cliente que ativa o WhatsApp. Todos os eventos chegam ao mesmo webhook, e o externalId diz de quem é cada um. Um cliente que precise de isolamento total pode ganhar um projeto só dele: projetos não custam nada, o que é cobrado são os números conectados.

Pareamento dentro do seu produto

Quando o cliente clica em "Conectar WhatsApp", o seu backend cria a conexão informando o externalId. Repetir a chamada com o mesmo externalId devolve a conexão que já existe, então um clique duplo não vira dois números:

const res = await fetch('https://api.apiwpp.com/connections', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APIWPP_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ tenantId: process.env.APIWPP_PROJECT_ID, externalId: customer.id }),
})
const { connectionId } = await res.json()

Depois, a API entrega o QR code pronto para exibir: GET /tenants/{id}/connections/{connId}/qr responde a imagem como data URL PNG e o status atual. O seu backend repassa só a imagem e o status para a tela; a chave de API nunca vai para o navegador. A tela consulta essa rota a cada poucos segundos e troca sempre pelo QR mais recente, porque o WhatsApp renova o código com frequência.

Para quem usa o seu produto no próprio celular, existe o código de pareamento de 8 caracteres, digitado em Aparelhos conectados › Conectar com número de telefone. Depois de conectado, o número funciona como um aparelho conectado: a sessão fica salva e criptografada, reinícios não pedem novo QR code e o celular do cliente pode ficar desligado. Os detalhes estão em conexão por QR code ou código de pareamento.

Um aviso honesto para a sua tela: desde meados de 2026, o WhatsApp pede a alguns celulares uma chave de acesso (passkey) depois da leitura do QR code, e essa etapa ainda não é concluída pela apiwpp. A conexão para com o status passkey_required. Números já pareados não são afetados.

Cada conversa chega ao seu webhook

Toda mensagem recebida por qualquer número conectado vira um POST ao webhook do projeto, sempre no mesmo envelope: type, connectionId, tenantId, externalId, timestamp e data. Rotear para a conta certa é uma consulta pelo externalId.

Os eventos que um CRM costuma usar:

Cada entrega é assinada com HMAC-SHA256 quando o projeto tem um segredo, e a entrega é pelo menos uma vez: grave os eventos de forma idempotente. Uma entrega que falha é tentada de novo, até 6 tentativas, e as que esgotarem ficam no registro de entregas para reenvio. O guia completo, com a verificação da assinatura em Node.js e PHP, está em webhooks do WhatsApp.

O que foi digitado no celular também aparece

O cliente continua usando o WhatsApp no celular, e essas respostas precisam aparecer no histórico do seu CRM. Para isso existe o evento opcional message.outgoing, ligado por projeto. Cada mensagem enviada pelo número numa conversa individual gera um evento com origin: PHONE quando foi digitada no celular, API quando foi o seu sistema, com o clientRef do envio de volta. Assim a conversa fica completa dos dois lados.

Chaves de API por componente

Um SaaS tem várias peças falando com a API, e nenhuma precisa de todos os poderes. As chaves têm escopos:

ComponenteEscopos
Tela de pareamento (backend)connections:read, connections:write
Painel interno de monitoramentoconnections:read
Worker de enviomessages:send
Script de configuração do webhookwebhooks:write

O QR code só é entregue a uma chave com connections:write: escanear conecta um número à sua conta, então um painel de suporte com connections:read acompanha o status sem conseguir parear nada. As chaves podem ter validade, ser revogadas e ser trocadas com um período de sobreposição, sem derrubar nenhum componente. Veja projetos e chaves de API.

OpenAPI 3.1 e clientes gerados

A especificação da API é pública, em OpenAPI 3.1, em português e em inglês, com referência interativa em docs.apiwpp.com. A partir dela são gerados clientes TypeScript (openapi-fetch) e PHP (OpenAPI Generator, com Guzzle), tipados rota por rota. Esses clientes ainda não estão publicados em registros de pacotes: são entregues a pedido ou gerados por você a partir da especificação. Para o seu time, isso significa autocompletar e checagem de tipos em cada chamada, e menos surpresa quando a API ganha um campo novo. Veja a integração com Node.js para um exemplo completo de envio e webhook.

Custo previsível para o seu plano

Um CRM não sabe quantas mensagens cada cliente vai trocar no mês. Na apiwpp, o preço é por número conectado por mês, com mensagens ilimitadas dentro dos limites que protegem o número, sem cobrança por mensagem. Cada cliente que ativa o WhatsApp soma um número à assinatura; números adicionados no meio do mês ficam disponíveis na hora e são cobrados de forma proporcional, e reduções valem a partir da fatura seguinte. Os valores de LITE e PRO estão em preços.

Vale lembrar que cada número tem a própria fila de envio, com limites por minuto, hora e dia e um teto de destinatários novos por dia. A apiwpp serve para os seus clientes conversarem com quem já é cliente deles, não para disparos em massa. Nenhuma ferramenta garante que um número nunca será restringido pelo WhatsApp.

O passo a passo técnico, com o código da tela de pareamento e do roteamento por externalId, está no guia como colocar o WhatsApp dentro do seu SaaS ou CRM.

Perguntas frequentes

Cada cliente do meu SaaS precisa de uma conta na apiwpp?

Não. A sua empresa tem uma conta, e cada cliente seu vira uma conexão dentro de um projeto seu. O cliente só escaneia o QR code que o seu produto mostra; ele não vê a apiwpp nem precisa de cadastro.

Como sei de qual cliente é cada mensagem recebida?

Todo evento de webhook traz o connectionId e o externalId da conexão. Se você criou a conexão com o id do cliente como externalId, basta usar esse valor para encontrar a conta no seu banco.

O meu cliente pode continuar usando o WhatsApp no celular?

Sim. A conexão é um aparelho conectado, como o WhatsApp Web, e o celular continua funcionando. Com o evento message.outgoing ligado, as mensagens digitadas no celular também chegam ao seu sistema, com origin: "PHONE".

Posso mostrar o QR code sem expor a minha chave de API?

Sim, e é assim que deve ser. O seu backend busca o QR code na API e repassa ao navegador só a imagem e o status. A chave fica no servidor.

Existe um SDK oficial para TypeScript ou PHP?

Existem clientes TypeScript e PHP gerados a partir da especificação OpenAPI 3.1. Eles ainda não estão publicados em registros de pacotes: você recebe pelo suporte ou gera com as mesmas ferramentas a partir da especificação pública.

Todos: Casos de uso →

Separe os números de cada cliente em projetos com chaves de API e webhook próprios, acompanhe tudo num painel só e pague uma fatura única, calculada por número conectado.

Cada mensagem que chega no número da empresa vira um evento no seu sistema: abra o ticket, distribua para a equipe e responda pela API, com texto, mídia, reações e o indicador de digitando.

Mande pelo WhatsApp os avisos que o seu sistema já gera para quem é cliente (conta, serviço, pedido, alerta), com templates, envios sem duplicidade e a confirmação de entrega e leitura no seu webhook.

Conecte seu primeiro número hoje.

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