Coexistência no WhatsApp: o que sincroniza e o que não

Atualizado em 25/10/2026

Na coexistência do WhatsApp, sincronizam com a API três coisas: os contatos do app que têm WhatsApp, o histórico de conversas individuais dos últimos seis meses (se a empresa autorizar) e, daí em diante, cada mensagem que a empresa envia pelo celular, por meio do webhook smb_message_echoes. Não sincronizam grupos, chamadas, catálogo, status, etiquetas, respostas rápidas nem listas de transmissão. A sincronização inicial precisa ser pedida em até 24 horas após a integração, e cada tipo só pode ser pedido uma vez.

Este artigo detalha o que entra, o que fica de fora, como os dados chegam no webhook e o que muda no app depois da integração. Se você ainda não conhece o recurso, comece por Coexistência no WhatsApp: mesmo número no app e na API.

Resumo: o que sincroniza e o que não

A tabela abaixo segue a comparação de recursos da página oficial Onboard WhatsApp Business app users:

Item	Sincroniza com a API?	Como chega
Contatos com número de WhatsApp	Sim	Webhook smb_app_state_sync
Conversas individuais dos últimos 6 meses	Sim, se a empresa autorizar	Webhook history
Mídia das conversas antigas	Só IDs de mídia dos últimos 14 dias	Webhooks history separados
Mensagens novas enviadas pelo app	Sim	Webhook smb_message_echoes
Mensagens novas recebidas	Sim	Webhook messages
Edição e exclusão de mensagens	Sim (passa a ser suportado)	Eventos de edição e revogação
Grupos	Não	—
Ligações de voz e vídeo	Não	—
Catálogo, pedidos, status	Não	—
Saudação, ausência, respostas rápidas, etiquetas	Não	—
Perfil comercial e canais	Não	—
Listas de transmissão	Não; ficam só leitura no app	—

Contatos: smb_app_state_sync

A sincronização de contatos é pedida com a API de dados do app (smb_app_data), logo depois da integração:

curl -X POST "https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/smb_app_data" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "sync_type": "smb_app_state_sync" }'

A resposta traz um request_id, que a Meta recomenda guardar para chamados de suporte. Em seguida chegam webhooks smb_app_state_sync com os contatos do app. Cada contato vem com full_name, first_name, phone_number e action:

• add: contato adicionado ou editado;
• remove: contato removido (sem os campos de nome).

Depois da carga inicial, o mesmo webhook continua disparando sempre que a empresa adiciona, edita ou remove um contato no app. Só contatos com número de WhatsApp entram.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Histórico: webhook history

O histórico é pedido com a mesma API, trocando o sync_type:

curl -X POST "https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/smb_app_data" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "sync_type": "history" }'

O que a documentação diz sobre o conteúdo:

• Período: mensagens enviadas e recebidas até 180 dias antes da integração.
• Só conversas individuais: mensagens de grupos não entram.
• Mídia: as mensagens de mídia chegam sem o ID do arquivo; IDs de mídia vêm em webhooks separados e só para mídias dos últimos 14 dias.
• Consentimento: a empresa escolhe no app se compartilha o histórico. Se recusar, chega um webhook history com o erro 2593109.

Fases e blocos

O histórico chega dividido em três fases, contadas a partir do dia da integração (dia 0):

Fase	Período
0	Dia 0 ao dia 1
1	Dia 1 ao dia 90
2	Dia 90 ao dia 180

Cada fase pode vir em vários blocos, que não chegam necessariamente em ordem. Use chunk_order para ordenar os blocos, phase para acompanhar a fase e progress para o total: 100 indica que a sincronização terminou. Se uma fase não tem mensagens, nenhum webhook é enviado para ela.

A Meta avisa que um único webhook pode descrever milhares de mensagens. A recomendação é gravar o payload primeiro e processar de forma assíncrona, para não estourar o tempo de resposta do endpoint.

Mensagens novas: smb_message_echoes

Depois da integração, o dono do número continua respondendo pelo celular. Cada mensagem enviada pelo app (ou por um dispositivo conectado compatível) gera um webhook smb_message_echoes, que você deve gravar na conversa do contato. Exemplo da documentação:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "102290129340398",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "15550783881",
          "phone_number_id": "106540352242922"
        },
        "message_echoes": [{
          "from": "15550783881",
          "to": "16505551234",
          "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
          "timestamp": "1700255121",
          "type": "text",
          "text": { "body": "Here's the info you requested! https://www.meta.com/quest/quest-3/" }
        }]
      },
      "field": "smb_message_echoes"
    }]
  }]
}

Repare que o array se chama message_echoes (não messages) e que existe o campo to, com o número do cliente. Sem esse webhook, seu sistema só enxerga as mensagens recebidas e as enviadas pela API: metade da conversa. Isso pesa em especial em multiatendimento, em que o atendente precisa ver o que o dono respondeu pelo celular.

Roteando os eventos no seu endpoint

Um esqueleto em Node.js para separar os campos:

export async function receberWebhook(body, fila) {
  for (const entry of body.entry ?? []) {
    for (const change of entry.changes ?? []) {
      const { field, value } = change;
      switch (field) {
        case 'messages':
          await fila.add('mensagem', value);           // recebidas e status
          break;
        case 'smb_message_echoes':
          await fila.add('eco_app', value.message_echoes);
          break;
        case 'history':
          await fila.add('historico', value);          // processar assíncrono
          break;
        case 'smb_app_state_sync':
          await fila.add('contatos', value);
          break;
        case 'account_update':
          await fila.add('conta', value);              // ex.: PARTNER_REMOVED
          break;
      }
    }
  }
}

Responda 200 rápido e processe na fila. Para testar esses eventos antes de ir para produção, veja como testar o webhook localmente, e para a estrutura geral, webhooks da API do WhatsApp.

Dispositivos conectados: onde a sincronização falha

O app aceita até quatro dispositivos conectados. Na integração, todos são desvinculados, e a empresa pode vincular de novo os compatíveis. WhatsApp para Windows e WhatsApp para WearOS não são compatíveis.

Consequências documentadas:

• mensagens de clientes que usam um dispositivo conectado incompatível não disparam o webhook messages, então não aparecem no seu sistema;
• nesses casos, pode chegar um webhook de mensagem não suportada com erro 131060, que também aparece quando alguém escreve pela primeira vez (comum após clique em anúncio) e costuma se resolver em segundos.

Quando receber 131060, oriente a empresa a conferir a mensagem no app.

O que muda no app depois da integração

Alguns recursos do app são desligados ou mudam:

• Mensagens temporárias: desativadas nas conversas individuais.
• Visualização única: desativada nas conversas individuais.
• Localização em tempo real: desativada nas conversas individuais.
• Listas de transmissão: desativadas; não dá para criar novas e as existentes ficam só para leitura.
• Edição e exclusão de mensagens: passam a ser suportadas e espelhadas.

O restante (grupos, ligações, catálogo, status, mensagens de saudação e ausência, respostas rápidas, etiquetas, perfil e canais) continua igual no app, mas não existe na API. Se a sua operação depende de etiquetas do app para organizar clientes, por exemplo, vai precisar recriar essa lógica no sistema.

Prazo de 24 horas: checklist

A sincronização inicial tem regras rígidas: a empresa precisa ser sincronizada em até 24 horas após a integração, e cada pedido (contatos e histórico) só pode ser feito uma vez. Perdeu o prazo ou precisa refazer? A empresa tem que se desconectar e passar pelo fluxo de novo.

1. Assine os campos account_update, history, smb_app_state_sync e smb_message_echoes antes de abrir o fluxo para o cliente.
2. Garanta que o endpoint grava o payload e responde rápido.
3. Peça contatos e histórico logo após a integração.
4. Avise o cliente que a sincronização está em andamento e peça que mantenha o app aberto.
5. Acompanhe progress até 100 e avise o cliente quando terminar.
6. Guarde os request_id das duas chamadas.

Para conferir se o número está em coexistência, consulte is_on_biz_app e platform_type no número; true e CLOUD_API indicam app e API ao mesmo tempo. Se o número ainda não está no app Business e você quer levá-lo direto para a API, veja como liberar um número que já está no WhatsApp.

Coexistência com a Vectalk

A Vectalk oferece coexistência: o número continua no app WhatsApp Business e passa a funcionar também na API. Os webhooks são os da documentação da Meta, então smb_message_echoes, history e smb_app_state_sync chegam nas URLs que você registrar com POST /api/webhooks, no mesmo formato mostrado acima. Detalhes de autenticação e webhooks estão na documentação; dúvidas sobre a sincronização inicial da sua conta podem ser tratadas pela Central de Ajuda. Para o panorama geral da API, veja o guia da API oficial do WhatsApp.

Perguntas frequentes

Quantos meses de histórico a coexistência traz?

Até seis meses (180 dias) de conversas individuais anteriores à integração, se a empresa autorizar o compartilhamento no app. Grupos não entram.

As fotos e áudios antigos vêm junto?

Só parcialmente. As mensagens de mídia do histórico chegam sem o arquivo; os IDs de mídia vêm em webhooks separados e apenas para mídias dos últimos 14 dias antes da integração.

Dá para sincronizar o histórico de novo depois?

Não pela API. Cada sincronização só pode ser pedida uma vez. Para repetir, a empresa precisa se desconectar e refazer o fluxo de integração.

Mensagens que eu mando pelo celular aparecem no sistema?

Sim, por meio do webhook smb_message_echoes, desde que enviadas pelo app ou por um dispositivo conectado compatível. Mensagens enviadas pelo app não abrem nem estendem a janela de atendimento da API; isso é detalhado em coexistência com CRM e limites.

Os grupos do app vão para a API?

Não. Os grupos continuam funcionando no app, mas não são sincronizados nem ficam disponíveis pela API.

---

Fontes oficiais consultadas em 25/10/2026: Onboard WhatsApp Business app users (Coexistence), Usar um número de WhatsApp existente, Referência do webhook messages.