WhatsApp Coexistence: use a API sem deixar de usar o WhatsApp Business

Que problema resolve

Antes da convivência (Coexistence), passar um número para a API significava tirá-lo do app: a equipe deixava de atender pelo celular e era preciso migrar tudo para um sistema novo. Com o Coexistence não é preciso escolher: o mesmo número, a mesma conta e as mesmas conversas, no app e no seu sistema ao mesmo tempo.

Serve quando o número já existe, já tem clientes que escrevem e alguém os atende pelo celular, e você quer somar automação, um CRM ou um bot sem cortar esse atendimento.

Como se conecta

O cadastro é feito com o Embedded Signup, a janela oficial da Meta. A pessoa dona do número faz login com o Facebook, escolhe ou cria o seu portfólio empresarial e, no final, escaneia um código QR pelo app WhatsApp Business (Configurações → Dispositivos conectados). É preciso uma segunda tela: o código aparece no computador e é escaneado com o celular.

Você pode fazer o cadastro no painel ou enviar ao seu cliente um link de cadastro com a sua marca, para que ele mesmo o faça sem entregar a você as credenciais da Meta.

Passo a passo e o que costuma travar o cadastro: Ao conectar · onde se escaneia o QR.

O que o seu sistema vê

• As mensagens que chegam (message.received), com o mesmo webhook para todos os seus números.
• O que a sua equipe digita no celular (message.echo): o conteúdo dessas mensagens chega ao seu sistema e não consome a cota do seu plano.
• O status de cada envio (message.status: enviado, entregue, lido, falhou).
• As mensagens que o contato edita ou apaga (message.edited, message.revoked): a versão final, com o id da original.
• O histórico das suas conversas, se você escolher ao conectar (history.batch e history.completed), além do resumo que a Meta compartilha ao conectar (history.synced).

Todos os eventos e o seu formato: Tipos de evento · Receber o webhook.

O histórico das suas conversas

O WAIA Connect entrega o histórico ao seu sistema se você escolher ao conectar. Antes de abrir a janela da Meta perguntamos «Você quer que entreguemos o histórico das suas conversas?» e é preciso responder sim ou não; vale em todos os planos.

A escolha é agora: a Meta compartilha o histórico uma única vez, quando você conecta o número, e se você escolher que não, depois não dá para pedir. Se disser sim, o WAIA Connect o baixa e guarda criptografado; quando o app WhatsApp Business perguntar, aceite compartilhar o histórico.

• O que traz: até 6 meses, com as mensagens das duas partes de cada conversa, sem grupos. O histórico continua no celular: nada é apagado nem movido de lá.
• Fotos, áudios e documentos: chegam sem o arquivo (como media_placeholder). A Meta manda o arquivo só dos últimos 14 dias, à parte e nem sempre; se chegar, traz o seu id e se baixa com GET /v1/media/{id} dentro de 7 dias. Cada um diz qual é o seu caso em connect.media: disponível até uma data, ou indisponível e por quê (mais de 14 dias · a Meta não conseguiu trazê-lo · aguardando).
• Como chega: por webhook, no evento history.batch (um lote de até 500 mensagens por evento, assinado como os demais) e history.completed quando não resta nada; ou pela API, com GET /v1/connections/{id}/history (paginado) e POST /v1/connections/{id}/history/{batchId}/ack para confirmar cada lote. Para recebê-lo é preciso um webhook ou usar a API.
• Quanto tempo guardamos: criptografado, no máximo 7 dias. É apagado assim que entregamos (um 2xx do seu webhook ou a confirmação pela API); o que não foi entregue é apagado depois de 7 dias de qualquer forma. Se no quinto dia você ainda não o recebeu, avisamos no painel e por e-mail, com a data em que será apagado.
• Em que ritmo: vai por uma fila separada, para não atrasar as mensagens ao vivo, e pode levar horas. Não conta como tráfego nem consome a cota do seu plano.
• Um lote pode chegar duas vezes: deduplique por batchId.
• Se ficássemos sem espaço, deixaríamos de guardar histórico novo e avisaríamos no painel e com o evento history.dropped. O resumo history.synced continua chegando como sempre.

Limitações da convivência (segundo a Meta)

São da Meta, não do WAIA Connect, e valem com qualquer provedor. A documentação oficial da Meta diz que, depois de conectar um número por convivência:

• O app precisa ser o WhatsApp Business 2.24.17 ou superior.
• As listas de transmissão e as mensagens de «visualização única» são desativadas; não há suporte para grupos, mensagens temporárias, localização em tempo real nem chamadas pela API.
• A Meta compartilha até 6 meses de histórico, uma única vez, ao conectar, e sem os grupos. Se você escolheu, o WAIA Connect o entrega ao seu sistema (detalhes acima).
• O número fica com um teto de 20 mensagens por segundo.
• Os dispositivos conectados são desconectados ao conectar e é preciso conectá-los de novo; a documentação cita exceções por plataforma.
• Se o celular principal não for usado por cerca de 14 dias, a Meta desconecta o número.

As mensagens enviadas pelo app continuam gratuitas; as que saem pela API têm o preço de sempre da Meta.

Quanto custa

Tarifa fixa por número conectado, sem teto de mensagens, com 14 dias de teste:

• Starter — US$ 12 por mês, 1 número
• Studio — US$ 25 por mês, 5 números
• Agencia — US$ 45 por mês, 12 números
• Escala — US$ 99 por mês, 30 números, e US$ 3 por número extra

A Meta cobra à parte as mensagens que lhe correspondem, no cartão da sua conta da Meta; o WAIA Connect não acrescenta nenhuma taxa. Detalhes na ajuda.

Perguntas frequentes

Posso continuar respondendo pelo celular depois de conectar o número à API?

Sim. Com o Coexistence o app WhatsApp Business continua funcionando no celular, e o que é digitado ali chega ao seu sistema como evento message.echo.

Perco as minhas conversas ao conectar?

Não: continuam no celular, e nada é apagado nem movido de lá. Se ao conectar você escolher receber o histórico, o WAIA Connect pede até 6 meses à Meta e o entrega ao seu sistema por webhook (history.batch) ou pela API, em até 7 dias. A escolha é agora: a Meta o compartilha uma única vez, ao conectar, e no app você precisa aceitar compartilhá-lo. Se não, a partir da conexão você recebe as mensagens novas.

O meu cliente precisa me dar o login do Facebook dele?

Não. Você envia um link de cadastro com a sua marca, ele faz o cadastro na janela da Meta com a própria sessão, e o número fica conectado à sua conta do WAIA Connect.

O que não funciona na convivência?

Segundo a Meta: listas de transmissão, mensagens de «visualização única», grupos, mensagens temporárias, localização em tempo real e chamadas pela API. O número fica com um teto de 20 mensagens por segundo.

É para mim se eu não vou programar nada?

Provavelmente não: o WAIA Connect conecta o WhatsApp a um sistema seu. Se você quer uma caixa de entrada para atender com a sua equipe e um assistente de IA, sem programar, isso é o WAIA.

Fontes

Consultadas em 28/09/2026.

• Meta — Onboarding WhatsApp Business app users (Coexistence)

Continue lendo

• Cloud API ou Coexistence: qual escolher
• Embedded Signup: o cadastro oficial da Meta
• O limite de 300 conversas novas do app
• Documentação da API
• Ajuda
• Política de privacidade