Pular para o conteúdo
apiwpp

Como colocar o WhatsApp dentro do seu SaaS ou CRM

Como integrar o WhatsApp no seu CRM ou SaaS: cada cliente conecta o próprio número pelo seu produto, as conversas chegam por webhook e o custo é por número.

Equipe apiwpp · 13 min de leitura

Os seus clientes já atendem pelo WhatsApp. O problema é que essas conversas vivem no celular de alguém, fora do CRM, fora do histórico do cliente e fora de qualquer relatório. A pergunta que chega ao time de produto é sempre a mesma: dá para cada cliente conectar o próprio número dentro do nosso sistema, sem sair da tela, e ver as mensagens ali mesmo?

Dá, e a arquitetura é mais simples do que parece. Cada cliente do seu SaaS 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 decide a qual conta cada evento pertence. Você não precisa hospedar sessões do WhatsApp, cuidar de proxies nem escrever uma fila de envio.

Este guia mostra o desenho completo com a apiwpp: como mapear clientes para conexões, como exibir o QR code no seu app, como receber as conversas no CRM (inclusive o que foi digitado no celular), como separar as chaves de API por componente e como prever o custo. Os exemplos usam Node.js, mas as chamadas são HTTP comuns.

A arquitetura: um número por cliente do seu produto

A apiwpp organiza tudo em três níveis. Entender cada um evita a maior parte das dúvidas de modelagem:

Na apiwppO que representa no seu SaaSObservação
OrganizaçãoA sua empresa, que assina a apiwppUma assinatura e uma fatura para todos os números
Projeto (tenant na API)O seu sistema, ou um ambiente deleTem o próprio endereço de webhook e as próprias chaves de API
ConexãoO número de WhatsApp de um cliente seuPareada como aparelho conectado, com sessão própria
externalIdO id do cliente no seu banco de dadosVolta em todo evento de webhook daquela conexão

O desenho mais comum é um projeto para o SaaS em produção (e outro para homologação, se você testar com números reais) e uma conexão para cada cliente que ativar o WhatsApp. Todos os eventos de todos os clientes chegam ao mesmo webhook do projeto, e o externalId diz de quem é cada um.

Se algum cliente precisar de isolamento total, com webhook e chaves separados, ele pode ganhar um projeto só dele. Projetos não custam nada; o que é cobrado são os números conectados. Esse é o modelo que agências costumam usar, e o guia sobre agências com vários números explora essa variação.

Cada conexão funciona como um aparelho conectado, do mesmo jeito que o WhatsApp Web. A sessão fica salva e criptografada nos servidores da apiwpp, então reinícios e atualizações não pedem um novo QR code, e o celular do seu cliente pode até ficar desligado.

Crie a conexão com o id do seu cliente

Quando um cliente clicar em "Conectar WhatsApp" no seu produto, o seu servidor cria a conexão no projeto e informa o externalId. A chave usada precisa do escopo connections:write:

const API = 'https://api.apiwpp.com'
const PROJECT_ID = process.env.APIWPP_PROJECT_ID!
const headers = {
  Authorization: `Bearer ${process.env.APIWPP_KEY}`,
  'Content-Type': 'application/json',
}

/** Creates (or finds) the WhatsApp connection of one customer of your SaaS. */
export async function connectionFor(customerId: string): Promise<string> {
  const res = await fetch(`${API}/connections`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ tenantId: PROJECT_ID, externalId: customerId }),
  })
  if (res.status === 402) throw new Error('number_limit_reached')
  if (!res.ok) throw new Error(`apiwpp ${res.status}: ${await res.text()}`)
  const { connectionId } = (await res.json()) as { connectionId: string }
  return connectionId
}

Guarde o connectionId na conta do cliente. Três detalhes deixam esse passo robusto:

  • O externalId evita conexões duplicadas. Se a requisição for repetida com o mesmo externalId, a API devolve a conexão que já existe em vez de criar outra. Um clique duplo no botão não vira dois números.
  • Cada conexão ocupa um número contratado. Além da quantidade contratada, a resposta é 402 com code: number_limit_reached. Trate esse caso no seu produto: avise a sua equipe ou aumente a quantidade de números da assinatura.
  • O projeto vem antes. O projeto e o endereço de webhook são configurados uma vez, fora do fluxo do cliente. O início rápido da documentação explica como obter o id do projeto.

Mostre o QR code dentro do seu produto

O pareamento é o momento em que o seu cliente mais precisa de ajuda. A boa notícia é que a API entrega o QR code pronto para exibir: GET /tenants/{id}/connections/{connId}/qr responde a imagem como data URL PNG, que vai direto num elemento de imagem, e o status atual da conexão.

A chave de API nunca deve chegar ao navegador. Crie uma rota no seu backend que confere quem está logado e repassa só o que a tela precisa:

app.get('/whatsapp/qr', requireLogin, async (req, res) => {
  const connId = req.user.account.whatsappConnectionId
  const r = await fetch(`${API}/tenants/${PROJECT_ID}/connections/${connId}/qr`, { headers })
  if (!r.ok) return res.sendStatus(502)
  const { qrCode, status } = (await r.json()) as { qrCode: string | null; status: string }
  res.json({ qrCode, status })
})

No navegador, consulte essa rota a cada 2 a 5 segundos e troque a imagem sempre pelo QR mais recente, porque o WhatsApp renova o código a cada poucos segundos e um código antigo não pareia:

async function watchPairing(img: HTMLImageElement, label: HTMLElement) {
  const { qrCode, status } = await (await fetch('/whatsapp/qr')).json()
  if (status === 'open') {
    img.hidden = true
    label.textContent = 'WhatsApp conectado.'
    return
  }
  if (status === 'passkey_required') {
    img.hidden = true
    label.textContent = 'O WhatsApp pediu uma chave de acesso no celular. Tente de novo mais tarde.'
    return
  }
  if (qrCode) img.src = qrCode
  setTimeout(() => watchPairing(img, label), 3000)
}
O QR code exibido dentro das configurações do seu produto, com as instruções ao lado.

Quando o status passa a open, o número está pronto para enviar e receber, e o projeto recebe o evento connection.status com o número pareado. Se ninguém escanear a tempo, a conexão fecha com o motivo qr_not_scanned; mostre um botão "Gerar novo QR code" que chama POST /tenants/{id}/connections/{connId}/connect pelo seu backend.

Quando o cliente está no próprio celular

Quem acessa o seu SaaS pelo celular não consegue escanear um QR code que está na mesma tela. Para esse caso existe o código de pareamento: POST /connections/{id}/pairing-code com o telefone no formato internacional devolve um código de 8 caracteres, que o cliente digita em WhatsApp › Aparelhos conectados › Conectar um aparelho › Conectar com número de telefone. Uma conexão pode pedir um código a cada 30 segundos, e um mesmo número recebe no máximo 5 códigos por hora.

Os detalhes de cada status e de cada resposta estão no tutorial sobre conectar um número por QR code e na página do recurso de conexão e pareamento.

Receba as conversas no seu CRM

Cada mensagem que chega a qualquer número conectado vira um POST ao webhook do projeto, sempre no mesmo envelope: type, connectionId, tenantId, externalId, timestamp e data. O externalId é o id do seu cliente, então rotear o evento para a conta certa é uma consulta simples.

Verifique a assinatura, responda 2xx em até 10 segundos e processe depois, fora da requisição:

import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'

const SECRET = process.env.WHATSAPP_WEBHOOK_SECRET
if (!SECRET) throw new Error('WHATSAPP_WEBHOOK_SECRET is not set')

function isSigned(rawBody: Buffer, timestamp = '', signature = ''): boolean {
  if (!/^\d+$/.test(timestamp) || !signature) return false
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const mac = createHmac('sha256', SECRET!).update(`${timestamp}.`).update(rawBody).digest('hex')
  const expected = Buffer.from(`sha256=${mac}`)
  const received = Buffer.from(signature)
  return expected.length === received.length && timingSafeEqual(expected, received)
}

const app = express()

app.post('/whatsapp/events', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!isSigned(req.body, req.get('X-Sales-Timestamp'), req.get('X-Sales-Signature'))) {
    return res.sendStatus(401)
  }
  await inbox.enqueue(JSON.parse(req.body.toString('utf8')))
  res.sendStatus(204)
})

No processamento, o externalId leva à conta e o type decide o que fazer:

async function handle(event: WebhookEvent) {
  if (!event.externalId) return // a connection created without your customer id
  const account = await accounts.findById(event.externalId)
  if (!account) return // connection of a customer you no longer serve

  switch (event.type) {
    case 'message.incoming':
      await conversations.appendIncoming(account.id, event.data)
      break
    case 'message.delivery':
      await conversations.updateStatus(account.id, event.data.messageId, event.data.status)
      break
    case 'connection.status':
      await accounts.updateWhatsappStatus(account.id, event.data)
      break
    default:
      // unknown types are ignored: the contract only grows
  }
}

Algumas regras que evitam retrabalho:

  • A entrega é pelo menos uma vez. O mesmo evento pode chegar de novo, então grave cada um de forma idempotente. Nos eventos de mensagens enviadas, use o messageId como chave.
  • Mídia chega como URL temporária. Um message.incoming com mídia traz data.media.url, assinada e com prazo de validade. Baixe o arquivo quando o evento chegar e guarde no seu armazenamento, em vez de guardar a URL.
  • Nem todo contato chega com telefone. Às vezes o remetente vem identificado só por um LID, com phone: null. Guarde a conversa pelo jid e atualize o contato quando chegar o evento contact.resolved.
  • Uma queda do seu endpoint tem conserto. Uma entrega que falha é tentada de novo, em até 6 tentativas no total. As que esgotarem as tentativas ficam no registro de entregas (GET /webhooks/deliveries), de onde podem ser reenviadas quando o seu servidor voltar.

O passo a passo completo da verificação, também em PHP, está no guia de webhooks do WhatsApp.

Espelhe o que foi digitado no celular

Aqui está o ponto que mais surpreende quem integra o WhatsApp num CRM: o cliente continua usando o celular. Ele responde pelo aplicativo, no meio da rua, e essa resposta precisa aparecer no histórico do seu sistema, senão a conversa fica pela metade.

Para isso existe o evento opcional message.outgoing. Ligue-o no projeto com uma chave que tenha o escopo webhooks:write:

curl -s -X PATCH "https://api.apiwpp.com/tenants/$PROJECT_ID" \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emitOutgoing": true}'

A partir daí, cada mensagem que o número enviar numa conversa individual gera um evento com o campo origin:

{
  "type": "message.outgoing",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "4821",
  "timestamp": "2026-08-19T13:20:00.000Z",
  "data": {
    "messageId": "3EB0A1B2C3D4E5F60718",
    "origin": "PHONE",
    "clientRef": null,
    "phone": "+5511988887777",
    "body": "Te espero amanhã às 10h!",
    "timestamp": 1790337600
  }
}

Com origin: "PHONE", a mensagem foi digitada no celular ou em outro aparelho conectado. Com origin: "API", foi o seu sistema que enviou, e o evento traz de volta o clientRef do envio, o que permite casar o evento com o registro que você já criou. Grupos não geram esse evento.

Separe as chaves de API por componente

Um SaaS tem várias peças que falam com a API, e nenhuma delas precisa de todos os poderes. As chaves de API da apiwpp têm escopo, então cada componente recebe só o que usa:

Componente do seu sistemaEscoposPor quê
Tela de pareamento (backend)connections:read, connections:writeCriar a conexão e receber o QR code
Painel de monitoramentoconnections:readVer o status das conexões; com esse escopo o QR code vem null
Worker de enviomessages:sendColocar mensagens na fila de cada número
Script de configuraçãowebhooks:writeDefinir o segredo do webhook e ligar o message.outgoing

Esse detalhe do QR code é proposital: escanear um QR code conecta um número à sua conta, então só uma chave com connections:write o recebe. Um painel interno de suporte pode acompanhar se os clientes estão conectados sem conseguir parear nada.

As chaves podem ter validade, ser revogadas e ser trocadas com um período de sobreposição, em que a antiga e a nova funcionam ao mesmo tempo. Assim você troca uma chave em produção sem derrubar nenhum componente. E vale repetir: nenhuma delas vai para o navegador do seu cliente.

Custos previsíveis: preço por número

Um CRM não sabe quantas mensagens cada cliente vai trocar no mês. Por isso o modelo de cobrança importa tanto quanto a API. Na apiwpp, o preço é por número conectado por mês, e as mensagens são ilimitadas dentro dos limites que protegem o número. Não há cobrança por mensagem nem cota mensal.

Na prática, para o seu SaaS:

  • O custo acompanha a ativação. Cada cliente que conecta o WhatsApp soma um número à assinatura; você sabe o custo de cada conta desde o primeiro dia e pode repassar isso no seu próprio plano.
  • Números novos entram na hora. Um número adicionado no meio do mês fica disponível imediatamente, e o restante do mês é cobrado de forma proporcional.
  • Reduzir também é simples. Menos números valem a partir da próxima fatura, e uma conexão só deixa de ocupar um número quando é apagada.
  • Uma fatura só. Todos os números de todos os projetos da organização vêm juntos, pagos por PIX, boleto ou cartão.

Os valores de cada plano e a calculadora estão na página de preços. O plano PRO acrescenta editar e apagar mensagens enviadas, marcar como lida, presença e o IP dedicado por número.

Boas práticas de UX no pareamento

A API resolve a parte técnica, mas a experiência do seu cliente depende da tela que você constrói. O que costuma funcionar:

  1. Explique antes de mostrar o QR code. Uma frase dizendo que o número vai aparecer em "Aparelhos conectados", como o WhatsApp Web, tira o medo de "instalar algo" no celular.
  2. Mostre o caminho exato. WhatsApp › Aparelhos conectados › Conectar um aparelho, ao lado da imagem.
  3. Ofereça o código de pareamento para quem está no celular, com o número já preenchido a partir do cadastro.
  4. Mostre o status ao vivo. "Aguardando leitura", "Conectado" e "Desconectado", vindos do status e do evento connection.status.
  5. Avise quando precisar de ação. Num fechamento com willReconnect: false, como logged_out (o cliente removeu o aparelho no celular), notifique o cliente para conectar de novo. Quedas passageiras se resolvem sozinhas.
  6. Deixe claro que os primeiros dias são mais lentos. Por 14 dias depois do pareamento, a fila aplica um aquecimento com limites menores. Reconectar sem necessidade recomeça esse período, então não faça logout como forma de "consertar" algo.
  7. Separe desconectar de excluir. Desconectar guarda a sessão e permite voltar sem QR code; excluir apaga a conexão, a sessão, os templates e o histórico, e libera o número contratado. Use a exclusão quando o cliente cancelar o seu SaaS.

Um cuidado honesto: desde meados de 2026, o WhatsApp pede a alguns celulares uma chave de acesso (passkey) logo 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, a sessão fica guardada e o cliente pode tentar de novo mais tarde ou usar outro número. Números já pareados não são afetados. Prever essa mensagem na sua tela evita um chamado de suporte.

Como começar hoje

  1. Liste as peças do seu sistema que vão falar com a API (pareamento, envio, webhook, painel interno) e defina os escopos de cada chave.
  2. Acrescente à conta do cliente, no seu banco, os campos do id da conexão e do status do WhatsApp, e use o id do cliente como externalId.
  3. Crie a rota de backend que repassa o QR code e a tela que consulta essa rota a cada poucos segundos.
  4. Suba o endpoint de webhook com a verificação HMAC e o roteamento por externalId, e ligue o message.outgoing se o seu CRM mostra o histórico completo.
  5. Crie sua conta na apiwpp e pareie o primeiro número pela sua própria tela. Para ver o mesmo fluxo por segmento, a página de WhatsApp para SaaS e CRMs resume o caso de uso.

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 normalmente. 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 com connections:write fica no servidor, e o navegador conversa apenas com o seu sistema.

Quanto custa colocar o WhatsApp para todos os meus clientes?

O preço é por número conectado por mês, com mensagens ilimitadas dentro dos limites de envio. Cada cliente que ativa o WhatsApp soma um número à sua assinatura, e números adicionados no meio do mês são cobrados de forma proporcional. Os valores estão na página de preços.

Posso enviar campanhas para a base dos meus clientes?

A fila de cada número limita o ritmo e a quantidade de destinatários novos por dia, justamente para reduzir o risco de bloqueio. Ela serve para conversar com quem já é cliente, não para disparos em massa. Nenhuma ferramenta garante que um número nunca será restringido pelo WhatsApp.


Leia também:

Conecte seu primeiro número hoje.

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