Solicitar historial bajo demanda de un chat

Solicita a WhatsApp una sincronización bajo demanda de mensajes antiguos de un chat, hacia atrás a partir de un mensaje de referencia (ancla).

Para recuperar un mensaje guardado que no se abrió (messageType: "error" en /message/find), use POST /message/reload.

Reglas:

• enviar number
• count es opcional y está limitado a 100
• messageid es opcional; cuando se indica, la API usa ese mensaje como referencia para buscar mensajes más antiguos del chat

Observación:

• Importante: la recuperación puede ocurrir solo después de abrir WhatsApp en el celular o dejarlo activo en segundo plano
• messageid define el mensaje de referencia para cargar el historial anterior; este campo no sirve para buscar ese mensaje específico
• si desea recuperar solo un mensaje específico X mediante el historial, indique como messageid el mensaje inmediatamente posterior a X y use count=1
• si no se indica messageid, la API usa el mensaje más antiguo conocido localmente de ese chat como referencia para buscar el historial anterior
• los mensajes se devuelven después vía webhook/SSE en eventos del tipo history y también quedan disponibles en /message/find

Resultado

La respuesta trae el request_id de la solicitud. Los mensajes llegan en el webhook/SSE history con event: "messages" y el request_id en cada mensaje. También viene en el nivel superior de los lotes messages y chats cuando todo el lote pertenece a la misma solicitud; los lotes mixtos pueden omitirlo en el nivel superior. La solicitud termina con un único lote event: "status" con el mismo request_id:

• status: completed cuando WhatsApp confirma la conclusión de la solicitud, timeout cuando no hubo respuesta concluyente en 2 minutos, blocked cuando el celular indica más mensajes, pero no entregó una página que avance
• success y error: solo cuando no hay próxima página posible; success: false y el motivo en error (pagination_no_progress, anchor_unavailable, history_access_unavailable o cursor_lookup_failed). Siempre vienen con blocked
• has_more: lo que declaró el celular. true hay más mensajes en el celular, false se llegó al inicio de la conversación, null no se confirmó. Algunos dispositivos declaran true en toda respuesta bajo demanda, incluso en la vacía: con ellos, la paginación termina en blocked con pagination_no_progress, nunca en has_more: false
• history_access: unavailable cuando hay más mensajes, pero WhatsApp no da acceso a ellos
• next_request: cuerpo listo para solicitar los mensajes anteriores; reenvíelo tal como vino. null cuando no hay una próxima solicitud utilizable

Para paginar, reenvíe next_request del resultado final hasta que venga null, esperando el resultado de cada solicitud. completed finaliza la solicitud, no toda la conversación. next_request: null sin has_more: false no comprueba el inicio de la conversación. El silencio o un lote con menos mensajes que count no indican el fin del historial: solo has_more: false lo indica.

Con blocked y error: "pagination_no_progress", finalice la paginación de ese chat sin repetir la solicitud automáticamente: es el fin de lo que el celular entrega a partir de esa ancla, y repetirla da el mismo resultado.

Cada chat tiene una solicitud activa a la vez. Repetir la solicitud con el mismo mensaje de referencia antes del status devuelve el mismo request_id (details.reused: true), sin un nuevo envío al celular. Una solicitud con otra referencia finaliza la anterior, que recibe su propio status final (en general timeout), y continúa normalmente. 409 solo ocurre cuando el requestId indicado ya está en uso.

El resultado final llega por webhook/SSE en hasta 2 minutos después de enviar la solicitud a WhatsApp (details.result_timeout_ms). Los mensajes atrasados pueden seguir llegando con el mismo request_id durante unos 5 minutos después de la solicitud, sin un segundo status final.

Modo síncrono (sync: true)

sync: true retiene la respuesta hasta el resultado, por hasta timeoutMs (predeterminado y máximo 25000). Los mensajes vienen en messages, y el nivel superior de la respuesta trae los mismos campos del status final (status, has_more, history_access, received_messages, next_request), además de received, timed_out y partial:

• resultado final dentro del plazo: 200 con ese resultado;
• llegaron mensajes, pero no el resultado: 200 con status: "pending", unos 2 segundos después del último mensaje;
• no llegó nada en el plazo: 202 con status: "pending", timed_out: true y messages vacío.

Con status: "pending", el resultado final llega después por el webhook/SSE history, con el mismo request_id. El webhook y el SSE también se envían en el modo síncrono, y los mensajes se guardan de la misma manera.

Mensaje de referencia eliminado

Si el ancla fue eliminada, la API intenta usar el siguiente mensaje válido de ese chat. details.requested_anchor_messageid informa la referencia solicitada, details.anchor_messageid la utilizada y details.anchor_replaced indica la sustitución. Sin alternativa, devuelve HTTP 400 con status: "anchor_unavailable"; intente sin messageid para usar el mensaje más antiguo guardado.