Como importar histórico de conversas e contatos do app WhatsApp Business pela API
Um número do app WhatsApp Business conectado pela Coexistência pode enviar seus contatos existentes e até 180 dias de conversas individuais à API uma única vez, em até 24 horas após o onboarding. Os contatos chegam como webhooks smb_app_state_sync e as conversas como webhooks history, em blocos ordenados por metadata.chunk_order; metadata.progress igual a 100 marca a importação como concluída. A empresa escolhe no app se quer compartilhar as conversas.
A easyCoexistence conecta os números do app WhatsApp Business dos seus clientes pela Coexistência e pede à Meta os contatos e o histórico de conversas assim que seu webhook está no lugar, então o histórico segue direto para o seu endpoint sem nada armazenado no caminho, e cada número é monitorado 24/7.
Até onde os webhooks de histórico retroagem, contando a partir do momento em que a empresa foi ativada na Cloud API.
Tempo após o onboarding em que os contatos e o histórico de mensagens de uma empresa devem ser sincronizados.
Código de erro no webhook de histórico quando a empresa desativou o compartilhamento de histórico no app WhatsApp Business.
Com que frequência cada sincronização pode ser executada; repeti-la exige que o cliente desconecte o número e conclua o Embedded Signup novamente.
O valor de progress que marca uma sincronização de histórico como concluída.
Como a importação começa?
Com um destino de webhook no número. Quando ele conecta com webhook_url já definido na sessão de conexão, ou quando você define um com PUT /connections/{id}/webhook em até 24 horas após a conexão, a easyCoexistence pede os dados à Meta uma única vez: POST /{phone_number_id}/smb_app_data com sync_type smb_app_state_sync para os contatos, depois history para as conversas, na ordem que a Meta documenta. O log de eventos do número registra history_sync_requested com os valores request_id da Meta para o suporte, ou history_sync_failed com o motivo.
O que os webhooks de contatos trazem?
O campo smb_app_state_sync, com um array state_sync no value. Cada item tem type contact; um objeto de contato com full_name, first_name e phone_number; uma ação add ou remove; e metadata.timestamp. Os nomes são omitidos na remoção. A Meta continua enviando esses webhooks após a importação sempre que a empresa adiciona, edita ou remove um contato no app WhatsApp Business, para que sua agenda acompanhe o celular.
O que os webhooks de histórico trazem?
O campo history, com um array history no value. Cada item tem metadata, com phase, chunk_order e progress, e threads, uma por cliente: o id da thread é o número do cliente, e messages lista essa conversa individual, recebidas e enviadas, com from indicando qual lado enviou cada uma. Uma mensagem traz id, timestamp, type, seu conteúdo sob o nome do type e history_context.status, como READ ou DELIVERED. Conversas em grupo não são incluídas.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WABA_ID>",
"changes": [
{
"field": "history",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
"history": [
{
"metadata": { "phase": 1, "chunk_order": 3, "progress": 42 },
"threads": [
{
"id": "<CUSTOMER_NUMBER>",
"messages": [
{
"from": "<CUSTOMER_NUMBER>",
"id": "wamid.<ID>",
"timestamp": "1790726400",
"type": "text",
"text": { "body": "<MESSAGE_TEXT>" },
"history_context": { "status": "READ" }
}
]
}
]
}
]
}
}
]
}
]
}Como as mensagens de mídia são importadas?
Primeiro como marcadores. Uma mensagem de mídia chega com type media_placeholder, sem conteúdo e sem ID de mídia. Depois a Meta envia webhooks de histórico separados com os IDs de mídia, mas apenas para mídias enviadas até 14 dias após o onboarding; baixe esses arquivos da Meta com o token do cliente. Mídias mais antigas continuam como marcador, então exiba-as como anexo indisponível em vez de deixar um vazio na conversa.
Em que ordem os blocos chegam, e quando a importação termina?
Não necessariamente em ordem. A Meta divide as conversas em três fases, da mais recente para a mais antiga: a fase 0 é o dia anterior ao onboarding, a fase 1 volta até o dia 90 e a fase 2 até o dia 180. Os blocos podem chegar fora de sequência, então ordene-os por metadata.chunk_order. metadata.progress é o percentual de toda a sincronização, e 100 significa concluída; o número da fase, sozinho, não indica que uma fase terminou.
E se a empresa recusar compartilhar as conversas?
Durante a conexão, o app WhatsApp Business pergunta à empresa se ela quer compartilhar o histórico de conversas. A recusa chega como um webhook de histórico sem mensagens e com um array errors cujo code é 2593109, com o título O histórico de sincronização foi desativado pela empresa no app WhatsApp Business. Os contatos continuam chegando, e as mensagens em tempo real fluem normalmente desde o momento em que o número foi conectado.
A importação pode ser executada de novo?
Não na mesma conexão. A Meta permite cada sincronização uma vez, em até 24 horas após o onboarding, e ela não pode ser reexecutada. Executar de novo exige que o cliente desconecte o número e o conecte outra vez, o que conta como um novo onboarding: com seu destino ainda registrado, a easyCoexistence pede a importação novamente, então deduplique pelo id de cada mensagem. Isso inclui um número que volta depois da regra dos 14 dias.
O que deve estar pronto antes de enviar o link de conexão?
Seu endpoint, no ar e respondendo. A Meta verifica a URL com o handshake GET quando o destino é aplicado, e a importação é solicitada uma única vez, logo em seguida. Se o handshake falhar, o número ainda conecta, mas sem destino; o last_error da sessão explica o motivo, e nada é importado a menos que você corrija o endpoint e o defina com PUT /connections/{id}/webhook dentro das 24 horas. Um número sem webhook_url não recebe importação alguma, porque o conteúdo enviado à easyCoexistence é descartado.
Como configurar
- Prepare the endpointDeploy an HTTPS URL with a random secret in its path that answers Meta's GET handshake and accepts bodies up to 3 MB.
- Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
- Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
- Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.
Erros comuns
- Rejeitar blocos grandes de histórico. Os payloads da Meta podem chegar a 3 MB, enquanto o Express processa JSON só até 100 KB por padrão; então aumente o limite, ou os blocos falham e a Meta continua repetindo o envio.
- Processar os blocos na ordem de chegada. Eles podem chegar fora de sequência; ordene por metadata.chunk_order e aguarde progress 100 antes de declarar a importação concluída.
- Inserir histórico sem deduplicar. Mensagens em tempo real podem se sobrepor à importação, e uma reconexão a executa de novo; então use o id de cada mensagem como chave.
- Enviar o link de conexão antes de o endpoint responder ao handshake da Meta. O destino então não é aplicado, e, a menos que você o defina em até 24 horas, o histórico do número nunca é importado.
De US$ 9 a US$ 0,75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Até onde vai a importação do histórico de conversas do WhatsApp?
Até 180 dias antes de o número ser ativado na Cloud API, cobrindo conversas individuais nos dois sentidos.
As conversas em grupo são importadas?
Não. A Meta deixa de fora as mensagens que fazem parte de uma conversa em grupo.
As conversas antigas de um cliente no WhatsApp chegam ao meu webhook?
Sim, até 180 dias de conversas individuais, enviadas uma única vez em até 24 horas após o onboarding, se a empresa escolher no app compartilhá-las.
A easyCoexistence guarda uma cópia das conversas importadas?
Não. A Meta envia o histórico direto para o seu webhook_url, como as mensagens em tempo real, e nada é armazenado no caminho.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em