> ## Documentation Index > Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi-es.json post /message/history-sync openapi: 3.1.0 info: title: WppFy - WhatsApp API version: 1.0.0 description: > API para la gestión de instancias de WhatsApp y comunicaciones. ## Recomendación Importante: WhatsApp Business **Se RECOMIENDA ENCARECIDAMENTE usar cuentas de WhatsApp Business** en lugar de WhatsApp normal para la integración; WhatsApp normal puede presentar inconsistencias, desconexiones, limitaciones e inestabilidad durante el uso con nuestra API. ## Autenticación - Los endpoints regulares requieren un header 'token' con el token de la instancia ## Estados de la Instancia Las instancias pueden estar en los siguientes estados: - `disconnected`: Desconectado de WhatsApp - `connecting`: En proceso de conexión - `connected`: Conectado y autenticado con éxito servers: - url: https://api.wppfy.com security: - token: [] tags: - name: Instancia description: > Operaciones relacionadas con el ciclo de vida de una instancia, como conectar, desconectar y verificar el estado. - name: Proxy description: > WppFy opera con un proxy interno por defecto. Puede mantener este valor predeterminado, configurar un proxy propio mediante `proxy_url` o usar su celular Android como proxy instalando la app en https://github.com/WppFy/silver_proxy_apk (APK directo: https://github.com/WppFy/silver_proxy_apk/raw/refs/heads/main/silver_proxy.apk). Si no se envía nada, se sigue usando el proxy interno. Las IPs son brasileñas; para clientes internacionales, considere un proxy de la región del cliente. - name: Perfil description: > Operaciones relacionadas con el perfil de la instancia de WhatsApp, como cambiar el nombre y la imagen de perfil. - name: Business description: > ⚠️ **EXPERIMENTAL** - Endpoints aún no probados por completo. Operaciones relacionadas con el perfil comercial de WhatsApp Business. Permite consultar y actualizar datos del perfil comercial como descripción, dirección, email, categorías y gestionar el catálogo de productos. **Requisitos:** - La cuenta conectada actualmente debe ser una cuenta **WhatsApp Business** - Las cuentas personales de WhatsApp no tienen perfil comercial **Nota:** Estos endpoints pueden no funcionar como se espera. Reporte los problemas encontrados. - name: Llamadas description: | Operaciones relacionadas con llamadas por WhatsApp. Permite realizar y rechazar llamadas de forma programática. - name: Enviar Mensaje description: > Endpoints para el envío de mensajes de WhatsApp con diferentes tipos de contenido. ## Campos Opcionales Comunes Todos los endpoints de envío de mensajes soportan los siguientes campos opcionales: - **`delay`** *(integer)*: Retraso en milisegundos antes del envío - Durante el retraso aparecerá "Escribiendo..." o "Grabando audio..." según el tipo - Ejemplo: `5000` (5 segundos) - **`readchat`** *(boolean)*: Marcar el chat como leído después del envío - Quita el contador de mensajes no leídos del chat - Ejemplo: `true` - **`readmessages`** *(boolean)*: Marcar los últimos mensajes recibidos como leídos - Marca los últimos 10 mensajes **recibidos** (no enviados por usted) como leídos - Útil para confirmar la lectura de mensajes pendientes antes de responder - A diferencia de `readchat`, que solo quita el contador de no leídos - Ejemplo: `true` - **`replyid`** *(string)*: ID del mensaje a responder - Crea una respuesta vinculada al mensaje original - El soporte varía según el tipo de mensaje - Ejemplo: `"3A12345678901234567890123456789012"` - **`mentions`** *(string)*: Números a mencionar (solo para envíos en grupos) - Números específicos: `"5511999999999,5511888888888"` - Mencionar a todos: `"all"` - **`forward`** *(boolean)*: Marca el mensaje como reenviado en WhatsApp - Agrega el indicador "Reenviado" al mensaje - Ejemplo: `true` - **`track_source`** *(string)*: Origen del rastreo del mensaje - Identifica el sistema o la fuente que está enviando el mensaje - Útil para integraciones (ej.: "chatwoot", "crm", "chatbot") - Ejemplo: `"chatwoot"` - **`track_id`** *(string)*: ID para el rastreo del mensaje - Identificador libre para dar seguimiento al mensaje en sistemas externos - Permite correlacionar mensajes entre diferentes plataformas - **Nota**: El sistema acepta valores duplicados; no hay validación de unicidad - Use el mismo ID en varios mensajes si tiene sentido para su integración - Ejemplo: `"msg_123456789"` ### Envío a Grupos - **`number`** *(string)*: Para enviar un mensaje a un grupo, use el ID del grupo que termina en `@g.us` - Ejemplo: `"120363012345678901@g.us"` - **Cómo obtener el ID del grupo:** - Use el `chatid` del webhook recibido cuando alguien envía un mensaje en el grupo - Use el endpoint `GET /group/list` para listar todos los grupos y sus IDs ## Placeholders Disponibles Todos los endpoints de envío de mensajes soportan placeholders dinámicos para personalización automática: ### Campos de Nombre - **`{{name}}`**: Nombre consolidado del chat, usando la primera opción disponible: 1. Nombre del lead (`lead_name`) 2. Nombre completo del lead (`lead_fullName`) 3. Nombre del contacto en WhatsApp (`wa_contactName`) 4. Nombre del perfil de WhatsApp (`wa_name`) - **`{{first_name}}`**: Primera palabra válida del nombre consolidado (mínimo 2 caracteres) ### Campos de WhatsApp - **`{{wa_name}}`**: Nombre del perfil de WhatsApp - **`{{wa_contactName}}`**: Nombre del contacto tal como está guardado en WhatsApp ### Campos del Lead - **`{{lead_name}}`**: Nombre del lead - **`{{lead_fullName}}`**: Nombre completo del lead - **`{{lead_personalid}}`**: ID personal (CPF, CNPJ, etc) - **`{{lead_email}}`**: Email del lead - **`{{lead_status}}`**: Estado actual del lead - **`{{lead_notes}}`**: Anotaciones del lead - **`{{lead_assignedAttendant_id}}`**: ID del agente asignado ### Campos Personalizados Los campos agregados mediante custom fields son accesibles usando `{{lead_field01}}` a `{{lead_field20}}` o usando `{{nomedocampo}}` definido en `/instance/updateFieldsMap`. ### Ejemplo de Uso ``` ¡Hola {{name}}! Vi que usted trabaja en {{company}}. ¿Su email {{lead_email}} es correcto? ``` **💡 Consejo**: Use `/chat/find` para buscar los datos del chat y ver los campos disponibles antes de enviar mensajes con placeholders. - name: Mensaje Async description: > Controles operativos de la cola interna de envío asíncrono usada cuando un endpoint de envío recibe `async=true`. Esta sección sirve para: - consultar el estado actual de la cola async - configurar el delay entre mensajes enviados con `async=true` - limpiar el backlog pendiente y cancelar mensajes aún no concluidos Alcance: - cubre solo la cola interna de mensajes directos async - no modifica mensajes ya enviados correctamente - name: Acciones en el mensaje y Búsqueda - name: Chats - name: Contactos - name: Bloqueos - name: Etiquetas - name: Grupos y Comunidades - name: Newsletters y Canales description: > Operaciones para la lectura y el seguimiento de canales de WhatsApp (newsletters). Casos de uso principales: - listar posts ya publicados en un canal - editar posts recientes de un canal - eliminar posts recientes de un canal - consultar views y reacciones de los posts - integrar canales sin necesidad de persistir los mensajes localmente Observaciones: - `/newsletter/messages` devuelve el contenido de los posts - `/newsletter/messages/edit` edita el contenido de posts recientes - `/newsletter/messages/delete` elimina posts recientes - las views (`viewsCount`) y reactions (`reactionCounts`) vienen en cada post de `/newsletter/messages`, no por evento de webhook - `/newsletter/updates` está obsoleta: WhatsApp no responde y la API devuelve 504 - los newsletters usan rutas propias y no deben usar `/message/edit` ni `/message/delete` - name: Respuestas Rápidas description: > Gestión de respuestas rápidas para agilizar la atención. **⚠️ Importante**: Este recurso solo es útil si utiliza un sistema frontend/interfaz personalizada para registrar y utilizar las respuestas. La API solo almacena las respuestas, pero no las aplica automáticamente. ### Cómo funciona: - **Crear**: Registre respuestas predefinidas con títulos y contenido - **Listar**: Recupere todas las respuestas registradas para mostrarlas en su interfaz - **Usar**: Su sistema frontend puede usar estas respuestas para agilizar la escritura ### Casos de uso: - Interfaces web personalizadas de atención - Apps móviles con sugerencias de respuesta - Sistemas CRM con plantillas de mensaje - Herramientas de productividad para agentes **No es un chatbot**: Para respuestas automáticas, use los recursos de Chatbot. - name: CRM description: > Sistema completo de gestión de relaciones con clientes integrado a la API. **💾 Almacenamiento interno**: Todos los datos de los leads se guardan directamente en la API, eliminando la necesidad de bases de datos externas. Su aplicación puede enfocarse solo en la interfaz y la lógica de negocio. ### Recursos disponibles: - **📋 20+ campos personalizables**: Nombre, teléfono, email, empresa, observaciones, etc. - **🏷️ Sistema de etiquetas**: Organice y categorice sus contactos - **🔍 Búsqueda avanzada**: Filtre por cualquier campo o etiqueta - **📊 Historial completo**: Todas las interacciones se registran automáticamente ### 🎯 Placeholders en mensajes: Use variables dinámicas en los mensajes para la personalización automática: ``` ¡Hola {{nombre}}! Vi que trabaja en {{empresa}}. ¿Su email {{email}} es correcto? Observaciones: {{observaciones}} ``` ### Flujo típico: 1. **Captura**: Los leads llegan vía WhatsApp o formularios 2. **Enriquecimiento**: Agregue datos usando `/chat/editLead` 3. **Segmentación**: Organice con etiquetas 4. **Comunicación**: Envíe mensajes personalizados con placeholders 5. **Seguimiento**: El historial se guarda automáticamente **Ideal para**: Ventas, marketing, atención, calificación de leads - name: Integración con Chatwoot description: > **🚧 INTEGRACIÓN BETA - Sistema de integración con Chatwoot para atención unificada** **⚠️ AVISO**: Esta integración está en fase BETA. Úsela bajo su propio riesgo. Recomendamos realizar pruebas en un entorno no productivo antes de usarla en producción. Esta categoría contiene recursos para configurar y gestionar la integración con Chatwoot, una plataforma de atención al cliente open-source. La integración permite centralizar las conversaciones de WhatsApp en Chatwoot. ### Recursos disponibles: - 🔧 **Configuración Completa**: Configure URL, tokens y credenciales de Chatwoot - 📬 **Sincronización Bidireccional**: Los mensajes nuevos entre WhatsApp y Chatwoot se sincronizan automáticamente - 📱 **Gestión de Contactos**: Sincronización automática de nombres y teléfonos - 🔄 **Actualización LID→PN**: Migración automática de Local ID a Phone Number - 🏷️ **Nombres Inteligentes**: Sistema de nombres con tilde (~) para actualización automática - 🚫 **Separación de Grupos**: Opción para ignorar grupos en la sincronización - 👤 **Firma de Mensajes**: Identificación del agente en los mensajes enviados - 🔗 **Webhook Automático**: URL generada automáticamente para configurar en Chatwoot ### 🏷️ Sistema de Nombres Inteligentes: - **Nombres con tilde (~)**: Se actualizan automáticamente cuando el contacto modifica su nombre en WhatsApp - **Nombres específicos**: Para un nombre fijo, quite la tilde (~) del nombre en Chatwoot - **Ejemplo**: "~Juan Pérez" = automático, "Juan Pérez" = fijo - **Migración LID→PN**: Sin duplicación de conversaciones durante la transición - **Respuestas nativas**: Aparecen directamente en Chatwoot sin marcas externas ### ⚠️ Limitaciones conocidas: - **Sincronización del historial**: No implementada - solo se sincronizan los mensajes nuevos ### Casos de uso: - Atención centralizada en Chatwoot - Equipos de soporte con múltiples agentes - Integración con CRM mediante Chatwoot - Centralización de canales de comunicación - Gestión automática de contactos y nombres **Ideal para**: Empresas con equipos de atención, call centers, soporte técnico (en entorno de pruebas) **Requiere**: Instancia de Chatwoot configurada, tokens de API y entorno de pruebas **🚧 Recuerde**: Integración en BETA - las funcionalidades pueden cambiar sin previo aviso - name: Server-Sent Events (SSE) paths: /message/history-sync: post: tags: - Acciones en el mensaje y Búsqueda summary: Solicitar historial bajo demanda de un chat description: > 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. requestBody: required: true content: application/json: schema: type: object required: - number properties: messageid: type: string description: >- ID del mensaje de referencia usado para buscar mensajes más antiguos del chat. example: 3EB01234567890ABCDEF number: type: string description: JID completo del chat. example: 5511999999999@s.whatsapp.net count: type: integer minimum: 1 maximum: 100 description: Cantidad deseada de mensajes en el sync. example: 20 default: 50 timestamp: type: integer description: >- Timestamp del mensaje de referencia, en milisegundos o segundos. Opcional; viene en `next_request` para que la referencia funcione incluso antes de que el mensaje esté guardado. example: 1706350400000 fromMe: type: boolean description: >- Indica si el mensaje de referencia fue enviado por la cuenta conectada. Opcional; viene en `next_request`. example: false requestId: type: string description: >- Identificador opcional elegido por el cliente; si se omite, la API genera un UUID. Se devuelve como request_id. Use un id nuevo por solicitud: un id ya en uso recibe `409`. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f fallbackMode: type: string enum: - try_alternates - exact default: try_alternates description: >- A dónde se envía la solicitud. `try_alternates` (predeterminado): en una conversación individual, envía por el número y por el LID del chat, porque el teléfono guarda cada conversación con una de las dos direcciones e ignora la solicitud enviada por la otra; la respuesta llega una sola vez. `exact`: envía solo por la dirección preferida del chat (el LID, cuando se conoce). En grupos, la solicitud siempre va solo al grupo. sync: type: boolean default: false description: >- Retiene la respuesta hasta el resultado de la solicitud, por hasta `timeoutMs`. Vea "Modo síncrono". timeoutMs: type: integer default: 25000 maximum: 25000 description: >- Solo con `sync: true`: espera máxima en milisegundos. Los valores mayores se convierten en 25000. examples: usando_ancora_explicita: summary: Obtener el historial anterior a un mensaje de referencia value: number: 5511999999999@s.whatsapp.net messageid: 3EB01234567890ABCDEF count: 20 recuperar_mensagem_especifica: summary: >- Recuperar solo el mensaje inmediatamente anterior a la referencia value: number: 5511999999999@s.whatsapp.net messageid: 3EB0MENSAGEM_LOGO_APOS_X count: 1 usando_ancora_local: summary: Reutilizar ancla local ya persistida value: number: 5511999999999@s.whatsapp.net count: 50 proxima_pagina: summary: Solicitar los mensajes anteriores con el next_request recibido value: number: 5511999999999@s.whatsapp.net count: 50 messageid: 3EB0MAIS_ANTIGA_RECEBIDA timestamp: 1706350400000 fromMe: false modo_sincrono: summary: Esperar el resultado en la respuesta (modo síncrono) value: number: 5511999999999@s.whatsapp.net count: 50 sync: true timeoutMs: 20000 responses: '200': description: >- Solicitud enviada con éxito. Los mensajes y el resultado llegan después por webhook/SSE. Con `sync: true`, también incluye los mensajes y el resultado de la solicitud. content: application/json: schema: type: object properties: success: type: boolean example: true request_id: type: string description: >- Identifica la solicitud. Aparece en los mensajes correlacionados y en el estado final del webhook/SSE history. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f message: type: string example: >- Solicitud de sincronización del historial enviada. Los mensajes se recibirán como eventos de sincronización del historial. details: type: object additionalProperties: true description: Metadatos adicionales de la operación properties: result_timeout_ms: type: integer example: 120000 description: Plazo para el resultado final por webhook/SSE. requested_anchor_messageid: type: string description: Referencia solicitada originalmente. anchor_messageid: type: string description: Referencia utilizada efectivamente. anchor_replaced: type: boolean description: >- La referencia eliminada fue sustituida por un mensaje válido posterior. reused: type: boolean description: >- La solicitud repite la referencia de una solicitud en curso: la API devuelve su `request_id` y no envía otra solicitud al teléfono. fallback_mode: type: string enum: - try_alternates - exact description: Modo de envío utilizado (`fallbackMode`). attempted_chats: type: array items: type: string description: Direcciones del chat a las que se envió el pedido. sync: type: boolean description: >- `true` cuando la respuesta esperó el resultado (`sync: true`). status: type: string enum: - completed - timeout - pending - blocked description: >- Solo en modo síncrono: resultado de la solicitud; `pending` cuando aún no llegó y llegará por webhook/SSE; `blocked` cuando el celular indica más mensajes, pero no entregó una página que avance (el motivo viene en `error`). request_chat: type: string description: 'Solo en modo síncrono: chat de la solicitud.' has_more: type: - boolean - 'null' description: >- Solo en modo síncrono: lo que declaró el celular. `true` hay más mensajes, `false` inicio de la conversación, `null` no confirmado. 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`. nullable: true history_access: type: string enum: - available - unavailable - unknown description: >- Solo en modo síncrono: `unavailable` cuando hay más mensajes sin acceso. received_messages: type: integer description: 'Solo en modo síncrono: cantidad de mensajes en `messages`.' next_request: type: - object - 'null' additionalProperties: true description: >- Solo en modo síncrono: cuerpo listo para solicitar los mensajes anteriores, o `null`. nullable: true received: type: boolean description: >- Solo en modo síncrono: llegaron mensajes o la solicitud se completó. timed_out: type: boolean description: 'Solo en modo síncrono: el plazo de `timeoutMs` se agotó.' partial: type: boolean description: >- Solo en modo síncrono: aún puede haber más mensajes (`has_more` distinto de `false`). messages: type: array items: type: object additionalProperties: true description: >- Solo en modo síncrono: mensajes de la solicitud, en el formato del evento `history`. error: type: string enum: - pagination_no_progress - anchor_unavailable - history_access_unavailable - cursor_lookup_failed description: >- Con `status: "blocked"` (y `success: false`): por qué no hay `next_request`. `pagination_no_progress`: a partir del mismo ancla, el celular no entregó una página que avance ni siquiera con el mayor `count` (en cada página sin avance, el `next_request` duplica el `count`, hasta 100): llegó vacía, sin un mensaje que sirva de ancla o repetida. Es el final de lo que el celular entrega a partir de ese ancla, pero WhatsApp no confirma que sea el inicio de la conversación; repetir la solicitud da el mismo resultado; `anchor_unavailable`: el mensaje de referencia ya no está disponible, solicite con otro; `history_access_unavailable`: el resto no está accesible; `cursor_lookup_failed`: falla al construir la siguiente solicitud, intente de nuevo. examples: async_padrão: summary: Solicitud de historial enviada value: success: true request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f message: >- History sync request sent. Messages will be received as history sync events. details: result_timeout_ms: 120000 requested_anchor_messageid: 3EB01234567890ABCDEF anchor_messageid: 3EB01234567890ABCDEF anchor_replaced: false sync_concluido: summary: Modo síncrono con resultado value: success: true sync: true request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f request_chat: 5511999999999@s.whatsapp.net status: completed has_more: true history_access: available received_messages: 1 next_request: number: 5511999999999@s.whatsapp.net count: 50 messageid: 3EB0MAIS_ANTIGA_RECEBIDA timestamp: 1706350400000 fromMe: false received: true timed_out: false partial: true messages: - messageid: 3EB0MAIS_ANTIGA_RECEBIDA chatid: 5511999999999@s.whatsapp.net fromMe: false messageTimestamp: 1706350400000 text: Mensagem antiga request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f '202': description: >- Solo con `sync: true`: no llegó nada dentro de `timeoutMs`. La solicitud continúa y el resultado llega por el webhook/SSE `history` con el mismo `request_id`. content: application/json: schema: type: object properties: success: type: boolean example: true request_id: type: string description: >- Identifica la solicitud. Aparece en los mensajes correlacionados y en el estado final del webhook/SSE history. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f message: type: string example: >- Solicitud de sincronización del historial enviada. Los mensajes se recibirán como eventos de sincronización del historial. details: type: object additionalProperties: true description: Metadatos adicionales de la operación properties: result_timeout_ms: type: integer example: 120000 description: Plazo para el resultado final por webhook/SSE. requested_anchor_messageid: type: string description: Referencia solicitada originalmente. anchor_messageid: type: string description: Referencia utilizada efectivamente. anchor_replaced: type: boolean description: >- La referencia eliminada fue sustituida por un mensaje válido posterior. reused: type: boolean description: >- La solicitud repite la referencia de una solicitud en curso: la API devuelve su `request_id` y no envía otra solicitud al teléfono. fallback_mode: type: string enum: - try_alternates - exact description: Modo de envío utilizado (`fallbackMode`). attempted_chats: type: array items: type: string description: Direcciones del chat a las que se envió el pedido. sync: type: boolean description: >- `true` cuando la respuesta esperó el resultado (`sync: true`). status: type: string enum: - completed - timeout - pending description: >- Solo en modo síncrono: resultado de la solicitud; `pending` cuando aún no llegó y llegará por webhook/SSE. request_chat: type: string description: 'Solo en modo síncrono: chat de la solicitud.' has_more: type: - boolean - 'null' description: >- Solo en modo síncrono: lo que declaró el celular. `true` hay más mensajes, `false` inicio de la conversación, `null` no confirmado. 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`. nullable: true history_access: type: string enum: - available - unavailable - unknown description: >- Solo en modo síncrono: `unavailable` cuando hay más mensajes sin acceso. received_messages: type: integer description: 'Solo en modo síncrono: cantidad de mensajes en `messages`.' next_request: type: - object - 'null' additionalProperties: true description: >- Solo en modo síncrono: cuerpo listo para solicitar los mensajes anteriores, o `null`. nullable: true received: type: boolean description: >- Solo en modo síncrono: llegaron mensajes o la solicitud se completó. timed_out: type: boolean description: 'Solo en modo síncrono: el plazo de `timeoutMs` se agotó.' partial: type: boolean description: >- Solo en modo síncrono: aún puede haber más mensajes (`has_more` distinto de `false`). messages: type: array items: type: object additionalProperties: true description: >- Solo en modo síncrono: mensajes de la solicitud, en el formato del evento `history`. examples: pendente: summary: No llegó nada dentro del plazo value: success: true sync: true request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f request_chat: 5511999999999@s.whatsapp.net status: pending has_more: null history_access: unknown received_messages: 0 next_request: null received: false timed_out: true partial: true messages: [] message: >- History sync request sent. The final result arrives by webhook/SSE with this request_id. '400': description: >- Payload inválido, modo inválido o ancla insuficiente. `anchor_unavailable`: el mensaje de referencia fue eliminado y no hay otro utilizable después de él; envíe sin `messageid` para usar el mensaje guardado más antiguo. content: application/json: schema: type: object properties: error: type: string example: number is required success: type: boolean status: type: string enum: - anchor_unavailable request_id: type: string request_chat: type: string requested_anchor_messageid: type: string has_more: type: - boolean - 'null' nullable: true next_request: type: - object - 'null' nullable: true examples: payload_invalido: summary: Payload inválido value: error: number is required anchor_unavailable: summary: Mensaje de referencia no disponible value: success: false error: anchor_unavailable status: anchor_unavailable request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f has_more: null next_request: null request_chat: 5511999999999@s.whatsapp.net requested_anchor_messageid: 3EB0ANCORA_APAGADA '409': description: >- El `requestId` informado ya está en uso por otra solicitud. Use un id nuevo; para repetir la misma solicitud, reenvíela sin `requestId`. content: application/json: schema: type: object properties: error: type: string example: history sync request_id already in use request_id: type: string description: Solicitud que ya usa ese id. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f '429': description: Límite de solicitudes de historial pendientes en la instancia. content: application/json: schema: type: object properties: error: type: string example: too many pending history sync requests '500': description: Error interno al solicitar el history sync content: application/json: schema: type: object properties: error: type: string example: 'Error al solicitar el historial: conexión cerrada' '503': description: La instancia se está deteniendo; la solicitud no se registró. content: application/json: schema: type: object properties: error: type: string example: instance is stopping components: securitySchemes: token: name: token type: apiKey in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.