Historial de mensajes

GET /api/v1/messages/whatsapp/history

Este endpoint permite consultar el historial de mensajes intercambiados entre un número de WhatsApp habilitado de la empresa y un cliente (identificado por su número de teléfono o customer_id), dentro de un rango de fechas especificado.

Es útil para monitorear la comunicación por WhatsApp, auditar interacciones y extraer el contexto de las conversaciones con clientes o usuarios finales.

A través de una solicitud GET, es posible recuperar el historial aplicando filtros obligatorios como el origen/identificador del cliente y el número de la empresa, además de filtros opcionales de paginación o límites de fechas.

A continuación, se describen los parámetros disponibles, ejemplos de solicitud y la estructura detallada de la respuesta esperada.

ℹ Recuerda que:

La URL base para todas las solicitudes es: https://tu-dominio.c3.pe

Importante: reemplaza tu-dominio por el nombre de dominio específico que te haya proporcionado C3.

Solicitud

Cabeceras

Encabezado	Tipo	Obligatorio	Descripción
Authorization	String	✅ Sí	Token de autenticación (Bearer Token).

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
`customer_source`	`String`	✅ Sí	Identificador del cliente. Admite número telefónico (ej. `51906051400`) o `customer_id` (ej. `PE.2490656651446152`).
`wa_number`	`String`	✅ Sí	Número de WhatsApp de la empresa (ej. `5115937474`).
`from_date`	`String`	✅ Sí	Fecha u hora de inicio en formato `YYYY-MM-DD` o `YYYY-MM-DD HH:mm:ss`.
`to_date`	`String`	❌ No	Fecha u hora final en formato `YYYY-MM-DD` (abarca hasta las 23:59:59) o `YYYY-MM-DD HH:mm:ss`.
`order`	`String`	❌ No (Por defecto `DESC`)	Ordenamiento de resultados por ID (`ASC` o `DESC`).
`with_pagination`	`Integer`	❌ No (Por defecto `0`)	Incluir la paginación en la respuesta (`1` para activarlo).
`per_page`	`Integer`	❌ No (Por defecto `50`)	Resultados por página (Min: 1, Max: 100). (requiere `with_pagination=1`).
`page`	`Integer`	❌ No (Por defecto `1`)	Número de página (requiere `with_pagination=1`).

Ejemplo de solicitud

http

GET /api/v1/messages/whatsapp/history?wa_number=5115937474&customer_source=PE.2490656651446152&from_date=2026-08-01 08:00:00&to_date=2026-08-05 18:00:00&order=DESC&with_pagination=1&per_page=20

Respuesta

La API devuelve un json con la siguiente estructura.

Sin PaginaciónCon Paginación

json

{
  "message": "Historial de mensajes obtenido correctamente",
  "data": [
    {
      "id": 70427,
      "customer_number": "51906051400",
      "customer_id": "PE.2490656651446152",
      "sender": "CUSTOMER",
      "direction": "INBOUND",
      "type": "text",
      "status": "RECEIVED",
      "created_at": "2026-08-04 11:24:13",
      "timestamp": 1785860653,
      "payload": {
        "text": "hola"
      },
      "agent_id": 0,
      "agent_name": null
    },
    {
      "id": 70431,
      "customer_number": null,
      "customer_id": "PE.2490656651446152",
      "sender": "AGENT",
      "direction": "OUTBOUND",
      "type": "text",
      "status": "READED",
      "created_at": "2026-08-04 11:28:38",
      "timestamp": 1785860918,
      "payload": {
        "text": "por favor requiero su numero"
      },
      "agent_id": 16,
      "agent_name": "Antonio Seguil Tamayo"
    }
  ]
}

json

{
  "message": "Historial de mensajes obtenido correctamente",
  "data": [
    {
      "id": 70427,
      "customer_number": "51906051400",
      "customer_id": "PE.2490656651446152",
      "sender": "CUSTOMER",
      "direction": "INBOUND",
      "type": "text",
      "status": "RECEIVED",
      "created_at": "2026-08-04 11:24:13",
      "timestamp": 1785860653,
      "payload": {
        "text": "hola"
      },
      "agent_id": 0,
      "agent_name": null
    }
  ],
  "pagination": {
    "total_items": 15,
    "items_per_page": 50,
    "current_page": 1,
    "total_pages": 1
  }
}

Definición de atributos

Objeto Principal de la Respuesta

Campo	Tipo	Descripción
`message`	String	Mensaje explicativo de la respuesta.
`data`	Array	Colección de objetos de mensajes devueltos.
`pagination`	Object \| null	Información de paginación si `with_pagination=1`, o `null` si no está activa.

Atributos del Mensaje (`data`)

Campo	Tipo	Descripción
`id`	Integer	Identificador único autoincremental del mensaje en el sistema.
`customer_number`	String \| null	Número telefónico del cliente (sanitizado, sin prefijo `+`). Puede ser `null` en mensajes salientes de agentes.
`customer_id`	String \| null	Identificador único del cliente en la plataforma (ej. `PE.2490656651446152`).
`sender`	String \| null	Identificador del tipo de emisor (`CUSTOMER`, `AGENT`, `BOT`, `SYSTEM`).
`direction`	String \| null	Dirección de la comunicación (`INBOUND`, `OUTBOUND`).
`type`	String \| null	Tipo de formato de contenido (`text`, `image`, `document`, `audio`, `video`, `sticker`, `template`, etc.).
`status`	String \| null	Estado del mensaje (`RECEIVED`, `QUEUED`, `SENDED`, `SENT`, `DELIVERED`, `READED`, `FAILED`).
`created_at`	String \| null	Fecha y hora del mensaje en formato `YYYY-MM-DD HH:mm:ss`.
`timestamp`	Integer \| null	Marca de tiempo Unix en segundos (Epoch Timestamp) correspondiente a la fecha del mensaje.
`payload`	Object \| null	Metadata estructurada o información extendida del contenido del mensaje.
`agent_id`	Integer \| null	Identificador numérico del agente que envió el mensaje (`0` si no aplica).
`agent_name`	String \| null	Nombre del agente que envió el mensaje (`null` si no aplica).

Atributos de Paginación (`pagination`)

Campo	Tipo	Descripción
`total_items`	Integer	Total general de registros encontrados para los criterios.
`items_per_page`	Integer	Límite de elementos por página solicitados.
`current_page`	Integer	Número de la página actual consultada.
`total_pages`	Integer	Cantidad total de páginas disponibles.

Estructura del `payload` según el Tipo de Mensaje

El campo payload de la respuesta varía dinámicamente según el valor del campo type de cada mensaje. A continuación se detallan los formatos del objeto payload agrupados por categoría:

Multimedia

Tipo	Descripción
`image`	Mensaje con imagen adjunta.
`audio`	Mensaje con archivo de audio o nota de voz adjunta.
`video`	Mensaje con archivo de video adjunto.
`document`	Mensaje con un documento adjunto (PDF, Word, etc.).
`sticker`	Mensaje de tipo sticker de WhatsApp.

json

{
  "caption": "Caption of image",
  "url": "whatsapp_attachments/test.png",
  "contentType": "image/png",
  "id": "Meta_handle_id",
  "sha256": "Meta_sha"
}

json

{
  "url": "<ATTACHMENT_URL>",
  "contentType": "audio/mp3",
  "id": "Meta_handle_id"
}

json

{
  "caption": "Caption of video",
  "url": "whatsapp_attachments/test.mp4",
  "contentType": "video/mp4",
  "id": "Meta_handle_id",
  "sha256": "Meta_sha",
  "filename": "Video name"
}

json

{
  "caption": "Caption of document",
  "url": "whatsapp_attachments/test.pdf",
  "contentType": "application/pdf",
  "id": "Meta_handle_id",
  "sha256": "Meta_sha",
  "filename": "Document name"
}

json

{
  "url": "whatsapp_attachments/test.webp",
  "contentType": "image/webp",
  "id": "Meta_handle_id",
  "sha256": "Meta_sha",
  "animated": true
}

Interactivos

Tipo	Descripción
`list`	Mensaje interactivo de tipo lista/menú de opciones.
`quick_reply`	Mensaje de respuesta rápida estructurado con opciones interactivas.
`list_reply`	Respuesta enviada por el cliente al seleccionar una opción de una lista (`list`).
`button_reply`	Respuesta enviada por el cliente al presionar un botón de un mensaje interactivo.
`button`	Respuesta a un botón de una plantilla de mensaje (`quick_reply` de plantilla).

json

{
  "title": "Title menu",
  "body": "Menu description",
  "button": "Button text",
  "items": [
    {
      "title": "Seleccione una opción",
      "rows": [
        {
          "id": "dsfsfddsfdsf",
          "title": "Opción 1",
          "description": "Opción descripción"
        }
      ]
    }
  ]
}

json

{
  "content": {
    "type": "text",
    "header": "Title",
    "text": "Menu description"
  },
  "options": [
    {
      "type": "text",
      "title": "Opcion 1",
      "id": "ofjdsifhdsfhd"
    }
  ]
}

json

{
  "id": "list_reply_id",
  "title": "list_reply_title",
  "description": "list_reply_description"
}

json

{
  "id": "list_reply_id",
  "title": "list_reply_title"
}

json

{
  "text": "No",
  "payload": "No-Button-Payload"
}

Informativos

Tipo	Descripción
`text`	Mensaje de texto plano estándar (incluye metadatos si proviene de un anuncio Click to WhatsApp).
`template`	Mensaje estructurado de plantilla de WhatsApp con sus componentes de configuración y aprobación.
`location`	Mensaje con coordenadas geográficas de ubicación compartida.
`contacts`	Mensaje que comparte uno o más contactos de la agenda telefónica.

json

{
  "text": "Hola como estas"
}

json

{
  "text": "Vi esto en tu anuncio",
  "referral": {
    "source_url": "AD_OR_POST_FB_URL",
    "source_id": "ADID",
    "source_type": "ad or post",
    "headline": "AD_TITLE",
    "body": "AD_DESCRIPTION",
    "media_type": "image or video",
    "image_url": "RAW_IMAGE_URL",
    "video_url": "RAW_VIDEO_URL",
    "thumbnail_url": "RAW_THUMBNAIL_URL",
    "ctwa_clid": "CTWA_CLID"
  }
}

json

{
  "id": "2614906395565761",
  "name": "maketing_para_clientes",
  "status": "APPROVED",
  "category": "MARKETING",
  "language": "es_MX",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": [
          "https://scontent.whatsapp.net/v/t61.29466-34/459086195_2614906398899094_6084613077189209306_n.png?ccb=1-7&_nc_sid=8b1bef&_nc_eui2=AeE50YMbsZ4vvFSeEIPbWV_OyNKNQ75nLnDI0o1DvmcucOtO_wylkD-8si_HdfdRvsWXYQ1u5FZ-_ukAWDs9olSF&_nc_ohc=7EyPzj776MwQ7kNvgHHgnGE&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&_nc_gid=A46UJZiy0WK4baNwRBn6xbG&oh=01_Q5AaIFO5xd95I8OnkGBfy7OO3K7XbnqwoWk4_Nl5btfD3IQM&oe=6718EDC8"
        ]
      }
    },
    {
      "text": "Hola Gabriel como estás, queremos informarte que nuestra plataforma C3 se renueva y tiene más canales de comunicación para que te comuniques con tus clientes.",
      "type": "BODY",
      "example": {
        "body_text": [
          [
            "Carlos"
          ]
        ]
      }
    },
    {
      "text": "C3 software - por GlobalIP",
      "type": "FOOTER"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "url": "https://c3.pe/",
          "text": "Revisa nuestra web",
          "type": "URL"
        }
      ]
    }
  ],
  "rejected_reason": "NONE"
}

json

{
  "latitude": "LOCATION_LATITUDE",
  "longitude": "LOCATION_LONGITUDE",
  "name": "LOCATION_NAME",
  "address": "LOCATION_ADDRESS"
}

json

[
  {
    "addresses": [
      {
        "city": "CONTACT_CITY",
        "country": "CONTACT_COUNTRY",
        "country_code": "CONTACT_COUNTRY_CODE",
        "state": "CONTACT_STATE",
        "street": "CONTACT_STREET",
        "type": "HOME or WORK",
        "zip": "CONTACT_ZIP"
      }
    ],
    "birthday": "CONTACT_BIRTHDAY",
    "emails": [
      {
        "email": "CONTACT_EMAIL",
        "type": "WORK or HOME"
      }
    ],
    "name": {
      "formatted_name": "CONTACT_FORMATTED_NAME",
      "first_name": "CONTACT_FIRST_NAME",
      "last_name": "CONTACT_LAST_NAME",
      "middle_name": "CONTACT_MIDDLE_NAME",
      "suffix": "CONTACT_SUFFIX",
      "prefix": "CONTACT_PREFIX"
    },
    "org": {
      "company": "CONTACT_ORG_COMPANY",
      "department": "CONTACT_ORG_DEPARTMENT",
      "title": "CONTACT_ORG_TITLE"
    },
    "phones": [
      {
        "phone": "CONTACT_PHONE",
        "wa_id": "CONTACT_WA_ID",
        "type": "HOME or WORK>"
      }
    ],
    "urls": [
      {
        "url": "CONTACT_URL",
        "type": "HOME or WORK"
      }
    ]
  }
]

Sistema y Llamadas

Tipo	Descripción
`system`	Notificación de cambio de número del usuario en WhatsApp.
`unknown`	Mensaje no admitido recibido de un cliente (por ejemplo, mensajes temporales que desaparecen).
`unsupported`	Mensaje no admitido o acción cuando se elimina un mensaje.
`call_permission_request`	Solicitud enviada al cliente para pedirle permiso para realizar una llamada telefónica.
`call_permission_reply`	Respuesta del cliente a la solicitud de permiso para realizar llamadas.

json

{
  "body": "NAME changed from PHONE_NUMBER to PHONE_NUMBER",
  "new_wa_id": "NEW_PHONE_NUMBER",
  "type": "user_changed_number"
}

json

{
  "code": 131051,
  "details": "Message type is not currently supported",
  "title": "Unsupported message type"
}

json

{
  "code": 131051,
  "title": "Message type unknown",
  "message": "Message type unknown",
  "error_data": {
    "details": "Message type is currently not supported."
  }
}

json

{
  "text": "Hola estimado, hace uno días atras nos indicaste que estas interesado en nuestros servicios, para coordinar mejor por favor aceptamos una llamada."
}

json

{
  "response": "accept|reject",
  "is_permanent": false,
  "expiration_timestamp": "95435435798",
  "response_source": "user_action|automatic"
}

Errores generales

Código HTTP	Tipo	Causa común
`401`	Unauthorized	El token de acceso no fue proporcionado en el encabezado `Authorization`, es inválido o ha sido revocado. Verifique que el token sea correcto y esté activo.
`422`	Unprocessable Entity	La solicitud fue entendida, pero contiene errores semánticos que impiden su procesamiento. Esto puede deberse a: 1. Parámetros faltantes o inválidos (ej, `from_date` no es una fecha válida); 2. Recurso inexistente (`wa_number` no registrado en el sistema); 3. Violación de reglas de negocio (el rango de fechas excede el límite permitido).
`500`	Server Error	Error interno del servidor. Intenta nuevamente más tarde o contacta soporte técnico.

Historial de mensajes ​

Solicitud ​

Cabeceras ​

Parámetros de consulta ​

Ejemplo de solicitud ​

Respuesta ​

Definición de atributos ​

Objeto Principal de la Respuesta ​

Atributos del Mensaje (data) ​

Atributos de Paginación (pagination) ​

Estructura del payload según el Tipo de Mensaje ​

Multimedia ​

Interactivos ​

Informativos ​

Sistema y Llamadas ​

Errores generales ​

Historial de mensajes

Solicitud

Cabeceras

Parámetros de consulta

Ejemplo de solicitud

Respuesta

Definición de atributos

Objeto Principal de la Respuesta

Atributos del Mensaje (`data`)

Atributos de Paginación (`pagination`)

Estructura del `payload` según el Tipo de Mensaje

Multimedia

Interactivos

Informativos

Sistema y Llamadas

Errores generales