Solicitar histórico sob demanda de um chat

Solicita ao WhatsApp um sync sob demanda de mensagens antigas de um chat, para trás a partir de uma mensagem de referência (âncora).

Para recuperar uma mensagem salva que não abriu (messageType: "error" no /message/find), use POST /message/reload.

Regras:

• envie number
• count é opcional e limitado a 100
• messageid é opcional; quando informado, a API usa essa mensagem como referência para buscar mensagens mais antigas do chat

Observação:

• Importante: a recuperação pode só acontecer depois de abrir o WhatsApp no celular ou deixá-lo ativo em segundo plano
• messageid define a mensagem de referência para carregar histórico anterior; esse campo não serve para buscar essa mensagem específica
• se você quiser recuperar apenas uma mensagem específica X via histórico, informe como messageid a mensagem logo depois de X e use count=1
• se messageid não for informado, a API usa a mensagem mais antiga conhecida localmente desse chat como referência para buscar histórico anterior
• as mensagens retornam depois via webhook/SSE em eventos do tipo history e também ficam disponíveis em /message/find

Resultado

A resposta traz o request_id do pedido. As mensagens chegam no webhook/SSE history com event: "messages" e o request_id em cada mensagem. Ele também vem no topo dos lotes messages e chats quando todo o lote pertence ao mesmo pedido; lotes mistos podem omiti-lo no topo. O pedido termina com um único lote event: "status" com o mesmo request_id:

• status: completed quando o WhatsApp confirma a conclusão do pedido, timeout quando não houve resposta conclusiva em 2 minutos, blocked quando o celular indica mais mensagens, mas não entregou uma página que avance
• success e error: só quando não há próxima página possível; success: false e o motivo em error (pagination_no_progress, anchor_unavailable, history_access_unavailable ou cursor_lookup_failed). Sempre vêm com blocked
• has_more: o que o celular declarou. true há mais mensagens no celular, false chegou ao início da conversa, null não foi confirmado. Alguns aparelhos declaram true em toda resposta sob demanda, inclusive na vazia: com eles, a paginação termina em blocked com pagination_no_progress, nunca em has_more: false
• history_access: unavailable quando há mais mensagens, mas o WhatsApp não dá acesso a elas
• next_request: corpo pronto para pedir as mensagens anteriores; reenvie como veio. null quando não há uma próxima requisição utilizável

Para paginar, reenvie next_request do resultado final até ele vir null, aguardando o resultado de cada pedido. completed encerra o pedido, não toda a conversa. next_request: null sem has_more: false não comprova o início da conversa. Silêncio ou um lote com menos mensagens que count não indicam o fim do histórico: só has_more: false indica.

Com blocked e error: "pagination_no_progress", encerre a paginação desse chat sem repetir o pedido automaticamente: é o fim do que o celular entrega a partir daquela âncora, e repetir dá o mesmo resultado.

Cada chat tem um pedido ativo por vez. Repetir o pedido com a mesma mensagem de referência antes do status devolve o mesmo request_id (details.reused: true), sem novo envio ao celular. Um pedido com outra referência encerra o anterior, que recebe o próprio status final (em geral timeout), e segue normalmente. 409 só ocorre quando o requestId informado já está em uso.

O resultado final chega por webhook/SSE em até 2 minutos após enviar o pedido ao WhatsApp (details.result_timeout_ms). Mensagens atrasadas podem continuar chegando com o mesmo request_id por cerca de 5 minutos após o pedido, sem um segundo status final.

Modo síncrono (sync: true)

sync: true segura a resposta até o resultado, por até timeoutMs (padrão e máximo 25000). As mensagens vêm em messages, e o topo da resposta traz os mesmos campos do status final (status, has_more, history_access, received_messages, next_request), além de received, timed_out e partial:

• resultado final dentro do prazo: 200 com esse resultado;
• chegaram mensagens, mas não o resultado: 200 com status: "pending", cerca de 2 segundos depois da última mensagem;
• nada chegou no prazo: 202 com status: "pending", timed_out: true e messages vazio.

Com status: "pending", o resultado final chega depois pelo webhook/SSE history, com o mesmo request_id. O webhook e o SSE são enviados também no modo síncrono, e as mensagens são salvas do mesmo jeito.

Mensagem de referência apagada

Se a âncora foi apagada, a API tenta usar a próxima mensagem válida desse chat. details.requested_anchor_messageid informa a referência solicitada, details.anchor_messageid a usada e details.anchor_replaced indica a substituição. Sem alternativa, retorna HTTP 400 com status: "anchor_unavailable"; tente sem messageid para usar a mensagem mais antiga salva.