> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Historial de chat

> Consulta el historial de mensajes de un bot

Obtén el historial de conversaciones de un bot para auditar interacciones, analizar métricas o depurar flujos. Este endpoint retorna los mensajes enviados y recibidos con soporte para paginación y filtros de tiempo.

***

## Endpoint

```
GET https://api.jelou.ai/v1/external/messages/history/{botId}
```

***

## Parámetros de ruta

| Campo     | Ubicación | Tipo   | Requerido | Descripción                                                        |
| --------- | --------- | ------ | --------- | ------------------------------------------------------------------ |
| **botId** | Path      | string | Sí        | Identificador único del bot del que deseas consultar el historial. |

***

## Parámetros de consulta

| Campo         | Ubicación | Tipo    | Requerido | Valor por defecto | Descripción                                                                  |
| ------------- | --------- | ------- | --------- | ----------------- | ---------------------------------------------------------------------------- |
| **limit**     | Query     | integer | No        | 10                | Número de mensajes a solicitar. Máximo: 50.                                  |
| **page**      | Query     | integer | No        | 1                 | Número de página.                                                            |
| **startAt**   | Query     | date    | No        | -                 | Fecha de inicio del rango a consultar. Formato ISO 8601.                     |
| **endAt**     | Query     | date    | No        | -                 | Fecha fin del rango a consultar. Formato ISO 8601.                           |
| **clientId**  | Query     | string  | No        | -                 | Filtra el historial por un clientId específico asociado a tus integraciones. |
| **messageId** | Query     | string  | No        | -                 | Devuelve la conversación que contiene el mensaje con este identificador.     |

<Tip>
  Si omites los campos opcionales, la API aplicará valores predeterminados para entregar la primera página con los mensajes más recientes.
</Tip>

***

## Ejemplos de solicitud

### Consulta básica

```bash theme={null}
curl --request GET \
  --url 'https://api.jelou.ai/v1/external/messages/history/BOT_ID?limit=10&page=1' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}'
```

### Con filtro de fechas

```bash theme={null}
curl --request GET \
  --url 'https://api.jelou.ai/v1/external/messages/history/BOT_ID?limit=20&page=1&startAt=2025-01-01T00:00:00.000Z&endAt=2025-01-31T23:59:59.000Z' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}'
```

### Con filtro de cliente

```bash theme={null}
curl --request GET \
  --url 'https://api.jelou.ai/v1/external/messages/history/BOT_ID?limit=10&page=1&clientId=CLIENT_ID' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}'
```

***

## Respuestas

<AccordionGroup>
  <Accordion title="200 - Respuesta exitosa">
    ```json theme={null}
    {
      "pagination": {
        "limit": 10,
        "page": 1,
        "total": 1,
        "offset": 0,
        "totalPages": 1
      },
      "_metadata": {},
      "results": [
        {
          "recipient": {
            "id": "RECIPIENT_ID",
            "names": "Cliente Ejemplo"
          },
          "sender": {
            "id": "BOT_ID",
            "name": "Mi Bot",
            "type": "WhatsApp"
          },
          "by": "bot",
          "messageId": "msg-12345-67890-4a38-abcde-fghij",
          "status": "DELIVERED_USER",
          "bubble": {
            "type": "TEXT",
            "text": "Hola, bienvenido a Jelou"
          },
          "createdAt": "2025-01-15T10:30:00.000Z"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="401 - Unauthorized">
    ```json theme={null}
    {
      "message": "Authentication failed"
    }
    ```
  </Accordion>

  <Accordion title="404 - Not Found">
    ```json theme={null}
    {
      "message": ["The Bot could not be found at the moment."],
      "statusMessage": "failed",
      "status": 0,
      "error": {
        "code": "E1019",
        "key": "BOT_NOT_FOUND",
        "description": "Error to be thrown when trying to get a Bot.",
        "developerMessages": {
          "es": "El botId no se encuentra en la base de datos o ha sido eliminado.",
          "en": "The botId is not found in the database or has been deleted."
        },
        "clientMessages": {
          "es": "El Bot no se pudo encontrar por el momento.",
          "en": "The Bot could not be found at the moment."
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="422 - Unprocessable Entity">
    ```json theme={null}
    {
      "message": ["Los valores ingresados no son correctos."],
      "statusMessage": "failed",
      "status": 0,
      "error": {
        "code": "E0422",
        "key": "VALIDATOR_ERROR",
        "description": "Error to be thrown when cannot process request because of incoming values",
        "developerMessages": {
          "es": "Los valores del request no son correctos para ser procesados.",
          "en": "The request values are not correct for processing."
        },
        "clientMessages": {
          "es": "Los valores ingresados no son correctos.",
          "en": "The values entered are not correct."
        }
      },
      "validationError": {
        "startAt": [
          {
            "es": "el campo startAt debe ser una fecha",
            "en": "the startAt field must be a Date"
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="500 - Internal Server Error">
    ```json theme={null}
    {
      "message": ["We are having trouble processing your request. Please try again later."],
      "statusMessage": "failed",
      "status": 0,
      "error": {
        "code": "E0000",
        "key": "UNKNOWN_ERROR",
        "description": "Error to be thrown when it couldn't be determined the reason of failure",
        "developerMessages": {
          "es": "Error inesperado ocurrido, revisar logs.",
          "en": "Unexpected error occurred, check logs."
        },
        "clientMessages": {
          "es": "Estamos teniendo problemas procesando la solicitud. Por favor intenta más tarde.",
          "en": "We are having trouble processing your request. Please try again later."
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Detalle de la respuesta

### Objeto pagination

| Campo          | Tipo    | Descripción                     |
| -------------- | ------- | ------------------------------- |
| **limit**      | integer | Número de registros por página. |
| **page**       | integer | Página actual.                  |
| **total**      | integer | Total de registros.             |
| **offset**     | integer | Desplazamiento desde el inicio. |
| **totalPages** | integer | Total de páginas disponibles.   |

### Objeto results

| Campo         | Tipo   | Descripción                                                             |
| ------------- | ------ | ----------------------------------------------------------------------- |
| **recipient** | object | Información del destinatario (id, names).                               |
| **sender**    | object | Información del remitente (id, name, type).                             |
| **by**        | string | Indica quién envió el mensaje: `bot` o `user`.                          |
| **messageId** | string | Identificador único del mensaje.                                        |
| **status**    | string | Estado del mensaje: `DELIVERED_USER`, `DELIVERED_CHANNEL`, `READ`, etc. |
| **bubble**    | object | Contenido del mensaje (type, text, mediaUrl, etc.).                     |
| **createdAt** | date   | Fecha de creación del mensaje en formato ISO 8601.                      |

***

## Límites y restricciones

<Note>
  **Límites importantes:**

  * **limit**: Valor máximo permitido es `50`
  * **page**: Debe ser un número entero positivo
  * **startAt/endAt**: Deben estar en formato ISO 8601 (ej: `2025-01-15T10:30:00.000Z`)
</Note>


## OpenAPI

````yaml GET /v1/external/messages/history/{botId}
openapi: 3.1.0
info:
  title: Jelou API
  description: >-
    API for the Jelou platform. Send messages, manage campaigns, handle
    conversations, users, databases, and widgets.
  version: 1.0.0
servers:
  - url: https://api.jelou.ai
    description: Production server
security:
  - basicAuth: []
tags:
  - name: Messages
    description: Send messages to users
  - name: Campaigns
    description: HSM campaigns and templates
  - name: Conversations
    description: Chat history and metrics
  - name: Users
    description: User state and cache management
  - name: Resources
    description: Media resource management
  - name: Datum
    description: Database CRUD operations
  - name: Widget
    description: Widget and room management
  - name: PMA Custom
    description: External support panel integration
paths:
  /v1/external/messages/history/{botId}:
    get:
      tags:
        - Conversations
      summary: Get Chat History
      description: Retrieve message history for a bot with pagination and date filters.
      operationId: getChatHistory
      parameters:
        - name: botId
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            maximum: 50
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: startAt
          in: query
          schema:
            type: string
            format: date-time
        - name: endAt
          in: query
          schema:
            type: string
            format: date-time
        - name: clientId
          in: query
          schema:
            type: string
        - name: messageId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: History retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatHistoryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    ChatHistoryResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        _metadata:
          type: object
        results:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        page:
          type: integer
        total:
          type: integer
        offset:
          type: integer
        totalPages:
          type: integer
    ChatMessage:
      type: object
      properties:
        recipient:
          type: object
          properties:
            id:
              type: string
            names:
              type: string
        sender:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            type:
              type: string
        by:
          type: string
          enum:
            - bot
            - user
        messageId:
          type: string
        status:
          type: string
        bubble:
          type: object
          properties:
            type:
              type: string
            text:
              type: string
            mediaUrl:
              type: string
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        statusMessage:
          type: string
        status:
          type: integer
        error:
          type: object
          properties:
            code:
              type: string
            key:
              type: string
            description:
              type: string
            developerMessages:
              type: object
            clientMessages:
              type: object
        validationError:
          type: object
  responses:
    Unauthorized:
      description: Unauthorized - Invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found - Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable entity - Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using Base64 encoded clientId:clientSecret

````