Como importar o histórico de conversas e contactos da app do WhatsApp Business através da API
Um número da app do WhatsApp Business ligado através da Coexistence pode enviar uma única vez à API os seus contactos existentes e até 180 dias de conversas individuais, nas 24 horas seguintes à integração. Os contactos chegam como webhooks smb_app_state_sync e as conversas como webhooks history, em blocos ordenados por metadata.chunk_order; metadata.progress com o valor 100 marca a importação como concluída. É a empresa que escolhe na app se partilha as conversas.
A easyCoexistence liga os números da app do WhatsApp Business dos seus clientes através da Coexistence e pede à Meta os contactos e o histórico de conversas assim que o seu webhook está configurado, pelo que o histórico segue diretamente para o seu endpoint sem ser armazenado pelo caminho, e cada número é monitorizado 24/7.
Até onde chegam os webhooks de histórico, contados a partir da data em que a empresa foi integrada na Cloud API.
Tempo após a integração em que os contactos e o histórico de mensagens de uma empresa têm de ser sincronizados.
Código de erro no webhook de histórico quando a empresa desativou a partilha de histórico na app do WhatsApp Business.
Frequência com que cada sincronização pode correr; repeti-la exige que o cliente desvincule e volte a concluir o Embedded Signup.
O valor de progress que marca uma sincronização do histórico como concluída.
Como começa a importação?
Com um destino de webhook no número. Quando o número se liga com webhook_url já definido na sessão de ligação, ou quando define um com PUT /connections/{id}/webhook nas 24 horas após a ligaçã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 contactos e depois history para as conversas, pela ordem que a Meta documenta. O registo de eventos do número regista history_sync_requested com os valores request_id da Meta para apoio ao cliente, ou history_sync_failed com o motivo.
O que transportam os webhooks de contactos?
Campo smb_app_state_sync, com um array state_sync no value. Cada item tem type contact; um objeto contact com full_name, first_name e phone_number; uma action de add ou remove; e metadata.timestamp. Na remoção, os nomes não são enviados. A Meta continua a enviar estes webhooks após a importação sempre que a empresa adiciona, edita ou remove um contacto na app do WhatsApp Business, para que a sua lista de contactos acompanhe o telemóvel.
O que transportam os webhooks de histórico?
Campo history, com um array history no value. Cada item contém metadata, com phase, chunk_order e progress, e threads, um por cliente: o id da thread é o número do cliente, e messages lista essa conversa individual, recebida e enviada, com from a indicar o lado que enviou cada mensagem. Cada mensagem tem id, timestamp, type, o seu conteúdo sob o nome do respetivo type e history_context.status, como READ ou DELIVERED. As conversas de grupo não estã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 são importadas as mensagens com multimédia?
Primeiro como marcadores. Uma mensagem multimédia chega com type media_placeholder, sem conteúdo e sem ID de media. A Meta envia depois webhooks de histórico separados com os IDs de media, mas apenas para ficheiros enviados nos 14 dias após a integração; esses ficheiros devem ser transferidos da Meta com o token do cliente. Os mais antigos continuam a ser marcadores, por isso mostre-os como um anexo indisponível em vez de deixar uma lacuna na conversa.
Em que ordem chegam os blocos e quando termina a importação?
Não necessariamente por ordem. A Meta divide as conversas em três fases, da mais recente para a mais antiga: a fase 0 é o dia anterior à integração, a fase 1 recua até ao dia 90 e a fase 2 até ao dia 180. Os blocos podem chegar fora de sequência, por isso ordene-os por metadata.chunk_order. metadata.progress é a percentagem de toda a sincronização, e 100 significa que está concluída; o número da fase, por si só, não indica que uma fase terminou.
E se a empresa recusar partilhar as conversas?
Durante a ligação, a app do WhatsApp Business pergunta à empresa se quer partilhar o histórico de conversas. A recusa chega como webhook de histórico sem messages e com um array errors cujo code é 2593109, com o título History sync is turned off by the business from the WhatsApp Business App. Os contactos continuam a chegar, e as mensagens em direto seguem normalmente desde o momento em que o número foi ligado.
A importação pode correr de novo?
Não na mesma ligação. A Meta permite cada sincronização uma vez, nas 24 horas após a integração, e não pode ser repetida. Para a executar de novo, o cliente tem de desligar o número e voltar a ligá-lo, o que conta como uma nova integração: com o destino ainda guardado, a easyCoexistence volta a pedir a importação, por isso elimine os duplicados pelo id de cada mensagem. Isto inclui um número que volta a ligar depois da regra dos 14 dias.
O que deve estar pronto antes de enviar a ligação?
O seu endpoint, em funcionamento e a responder. A Meta verifica o URL através do handshake GET quando o destino é aplicado, e a importação é pedida uma única vez, logo a seguir. Se o handshake falhar, o número liga-se mesmo assim, mas sem destino; o last_error da sessão explica porquê, e nada é importado, a não ser que corrija o endpoint e o defina com PUT /connections/{id}/webhook dentro das 24 horas. Um número sem webhook_url não recebe qualquer importação, 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 atingir 3 MB, mas o Express só lê JSON até 100 KB por predefinição; aumente o limite, ou os blocos falham e a Meta continua a voltar a tentar.
- Processar os blocos pela ordem de chegada. Podem chegar fora de sequência, por isso ordene-os por metadata.chunk_order e aguarde até progress chegar a 100 antes de dar a importação como concluída.
- Inserir histórico sem eliminar duplicados. As mensagens em direto podem sobrepor-se à importação e uma nova ligação volta a executá-la, por isso identifique cada mensagem pelo id.
- Enviar a ligação antes de o endpoint responder ao handshake da Meta. O destino não é então aplicado e, a não ser que o defina nas 24 horas, o histórico do número nunca é importado.
De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
Até onde recua a importação do histórico de conversas do WhatsApp?
Até 180 dias antes de o número ser integrado na Cloud API, abrangendo conversas individuais nos dois sentidos.
As conversas de grupo são importadas?
Não. A Meta deixa de fora as mensagens que fazem parte de uma conversa de grupo.
As conversas antigas do WhatsApp de um cliente chegam ao meu webhook?
Sim, até 180 dias de conversas individuais, enviadas uma única vez nas 24 horas após a integração, se a empresa escolher na app partilhá-las.
A easyCoexistence guarda uma cópia das conversas importadas?
Não. A Meta envia o histórico diretamente para o seu webhook_url, tal como as mensagens em direto, e nada é armazenado pelo caminho.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em