Pular para o conteúdo
D-APITestar grátis

api oficial · coexistência

Coexistência WhatsApp Business App e API no mesmo número do seu cliente

Com a coexistência WhatsApp Business App e API, o cliente do seu SaaS continua atendendo pelo app no celular enquanto o seu produto envia e recebe pela API oficial, no mesmo número e com o histórico importado.

SaaS testa 14 dias com o time técnico ajudando na integração.

conexões na D-API
1.875
de uptime garantido em contrato
99,9%
datacenters no Brasil
4
por ligação de WhatsApp na API não-oficial
R$ 0
  • O app continua no celular

    O cliente não troca de número nem abandona o app WhatsApp Business. O seu SaaS passa a operar o mesmo número pela API oficial.

  • Mensagens do app chegam no seu webhook

    O que o cliente envia pelo celular chega como messages.received com fromMe true, marcado com coexistence echo.

  • Histórico importado na conexão

    As conversas anteriores entram no histórico da D-API e no seu webhook, marcadas com coexistence history.

  • Mesmo botão de onboarding

    É o mesmo DApiConnect do Embedded Signup, com mode coexistence. O cliente escaneia um QR no app e a conexão volta pronta.

A coexistência WhatsApp Business App e API é o modo da Meta em que um mesmo número roda ao mesmo tempo no app WhatsApp Business do celular e na Cloud API. Para o seu SaaS, ela destrava a venda da API oficial para o cliente que tem medo de perder o que já construiu: o dono da loja que responde clientes pelo celular há anos, a clínica cuja recepção usa o app no balcão. Ele mantém o app, e o seu produto ganha o número pela API oficial, com as conversas antigas trazidas para dentro.

Para quem a coexistência faz sentido

O perfil típico é o pequeno e médio negócio que já atende pelo app WhatsApp Business e foi convencido a adotar a oficial, por exigência de um parceiro, por volume de notificação ou por querer templates aprovados. Sem coexistência, a conversa de venda esbarra em “vou ter que parar de usar o app?”. Com ela, a resposta é não.

Vale comparar com as alternativas que o seu SaaS já oferece:

Situação do cliente Caminho
Quer conectar o número do app e começar hoje, sem template API não oficial, por QR code
Quer a API oficial e manter o app no mesmo número Coexistência
Quer a API oficial num número dedicado à operação Embedded Signup padrão, número novo

A não oficial continua sendo o caminho mais rápido para a maior parte da base. A coexistência entra quando o cliente pede a oficial e não quer abrir mão do app.

Como o cliente conecta

O onboarding é o mesmo do Embedded Signup, com uma opção a mais. No frontend do seu SaaS, o DApiConnect recebe mode: "coexistence":

import { DApiConnect } from "d-api-sdk/connect";

const connect = new DApiConnect({ publishableKey: "pk_live_…" });

const { connectionId } = await connect.start({
  mode: "coexistence",
  webhookUrl: "https://seu-saas.com/hooks/dapi",
  metadata: { tenantId: "loja-centro-08" },
});

A janela vai direto para a Meta e volta com o connectionId. A diferença em relação ao fluxo padrão está no que a Meta pede ao cliente: escanear um QR code no app WhatsApp Business do número que ele quer conectar. Escaneado o código, a conexão é criada na sua conta D-API como qualquer outra conexão oficial, e o connectionId passa a ser o sessionId nas rotas de envio.

No painel da D-API, a mesma opção aparece como Coexistência (app WhatsApp Business), ao lado do Embedded Signup padrão, para quem prefere conectar o primeiro número sem escrever código.

O histórico chega junto

O argumento mais forte para o cliente é não começar do zero. Logo depois da conexão, a Meta envia o histórico de conversas do app, e a sincronização pode levar alguns minutos. A orientação para o cliente é manter o app WhatsApp Business aberto no celular durante esse período, para agilizar a importação. As conversas vão aparecendo no histórico conforme chegam.

Na D-API, cada mensagem do histórico entra no armazenamento de conversas da conexão e é repassada ao seu webhook. No modo normalized, ela chega como um messages.received comum, com dois detalhes: fromMe indica se a mensagem foi da empresa ou do contato, e o campo coexistence vem com o valor "history". Pela regra da Meta, o histórico cobre até 180 dias de conversa.

Um aviso prático para o seu onboarding: a importação depende da assinatura de webhook do número na Meta. Se ela não acontecer automaticamente, o painel da D-API avisa e orienta a fazer a inscrição no painel da Meta. Sem ela, o histórico não é sincronizado.

O que o cliente faz no celular aparece no seu produto

Depois da conexão, o cliente continua respondendo pelo app quando quiser. Cada mensagem que ele envia pelo celular chega ao seu webhook, e isso evita o pior cenário de uma inbox compartilhada: o atendente no seu SaaS respondendo algo que o dono já respondeu pelo celular cinco minutos antes.

A D-API traduz os três tipos de evento de coexistência da Meta para o formato canônico:

O que aconteceu Campo da Meta Evento no modo normalized
A empresa enviou pelo app smb_message_echoes messages.received com fromMe: true e coexistence: "echo"
Histórico importado history messages.received com coexistence: "history"
Contato adicionado, alterado ou removido no app smb_app_state_sync contacts.update ou contacts.delete

Um eco de mensagem enviada pelo celular fica assim:

{
  "event": "messages.received",
  "sessionId": "cloud-3f2a…",
  "data": {
    "id": "wamid.HBgM…",
    "from": { "jid": "[email protected]" },
    "to": { "jid": "[email protected]" },
    "fromMe": true,
    "message": "Seu pedido sai hoje à tarde.",
    "timestamp": 1761955200,
    "is_group": false,
    "type": "text",
    "coexistence": "echo"
  }
}

Mídia de eco e de histórico segue o mesmo caminho das mensagens recebidas: o arquivo é baixado da Meta e hospedado antes do envio ao webhook, então o payload já traz um media_url que o seu backend consegue baixar.

Com webhookMode: "meta_passthrough", esses eventos chegam no formato cru da Meta, com os campos originais, para quem já tem parser próprio.

Como tratar os ecos no seu handler

A regra que funciona é tratar coexistence: "echo" como uma mensagem enviada pela empresa por outro canal. Ela entra na timeline da conversa como saída, mas não dispara automação de resposta, porque não há o que responder. Para coexistence: "history", a recomendação é gravar sem notificar o atendente: são conversas antigas, e uma enxurrada de alertas no primeiro minuto assusta o cliente. O guia de webhooks da API de WhatsApp cobre deduplicação e processamento em fila.

Limites que mudam com a coexistência

Alguns números são diferentes num número em coexistência, e o seu time comercial deve conhecê-los antes de vender. O envio pela API fica em cerca de 20 mensagens por segundo, contra cerca de 80 por segundo num número só na API oficial, além do limite diário do tier. Para um SaaS de atendimento ou agendamento, 20 por segundo costuma sobrar. Para quem planeja disparos grandes, um número dedicado pelo fluxo padrão é a escolha mais segura.

Também vale lembrar que o cliente continua sujeito às regras da Meta para o que sai pela API: fora da janela de 24 horas, a mensagem iniciada pela empresa precisa ser um template aprovado, enviado por POST /api/v1/messages/send/template.

Uma integração para todos os perfis

Para o código do seu SaaS, uma conexão em coexistência é uma conexão oficial com eventos a mais. O mesmo handler de webhook serve as conexões não oficiais, as oficiais padrão e as de coexistência, porque o formato normalizado é o mesmo, e o campo coexistence aparece só quando é relevante. O artigo API oficial e não oficial na mesma integração mostra como modelar o tipo de conexão no tenant.

Por onde começar

Adicione ao seu onboarding uma pergunta simples antes da conexão oficial: “o número já roda no app WhatsApp Business e você quer continuar usando?”. Se sim, abra o DApiConnect com mode: "coexistence". Depois ajuste o handler para reconhecer echo e history. O fluxo de provedor completo, com opções e erros, está na documentação da D-API.

Time D-API. Atualizado em .

Perguntas frequentes

Qualquer número pode entrar em coexistência?

Valem as regras da Meta: o número precisa ter uso real anterior no app WhatsApp Business.

O app WhatsApp Business perde alguma função na coexistência?

Sim. Pela regra da Meta, algumas funções do app deixam de funcionar no número em coexistência, como listas de transmissão e mensagens temporárias. Vale avisar o cliente antes de conectar.

Posso testar coexistência no período de teste da D-API?

Pode. O trial inclui webhook, templates e coexistência, usando um número real. Os números de teste da Meta não passam pelo Embedded Signup.

Meu cliente usa a API não oficial hoje. Como ele vai para a oficial sem trocar de número?

Se o número roda no app WhatsApp Business, o caminho é conectar por coexistência. Se não, ele conecta como número novo pelo Embedded Signup padrão.

Como meu SaaS sabe que uma conexão está em coexistência?

A D-API marca a conexão quando chega o primeiro evento de coexistência da Meta, e o painel passa a mostrar que o número também usa o app WhatsApp Business. No seu backend, o sinal prático é o campo coexistence nos eventos.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.