> ## 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.

# Chat history

> Query the message history of a bot

Retrieve the conversation history of a bot to audit interactions, analyze metrics, or debug flows. This endpoint returns sent and received messages with support for pagination and time filters.

***

## Endpoint

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

***

## Path Parameters

| Field     | Location | Type   | Required | Description                                                   |
| --------- | -------- | ------ | -------- | ------------------------------------------------------------- |
| **botId** | Path     | string | Yes      | Unique identifier of the bot whose history you want to query. |

***

## Query Parameters

| Field         | Location | Type    | Required | Default value | Description                                                                   |
| ------------- | -------- | ------- | -------- | ------------- | ----------------------------------------------------------------------------- |
| **limit**     | Query    | integer | No       | 10            | Number of messages to request. Maximum: 50.                                   |
| **page**      | Query    | integer | No       | 1             | Page number.                                                                  |
| **startAt**   | Query    | date    | No       | -             | Start date of the range to query. ISO 8601 format.                            |
| **endAt**     | Query    | date    | No       | -             | End date of the range to query. ISO 8601 format.                              |
| **clientId**  | Query    | string  | No       | -             | Filters the history by a specific clientId associated with your integrations. |
| **messageId** | Query    | string  | No       | -             | Returns the conversation that contains the message with this identifier.      |

<Tip>
  If you omit optional fields, the API will apply default values to deliver the first page with the most recent messages.
</Tip>

***

## Request Examples

### Basic query

```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}}'
```

### With date filter

```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}}'
```

### With client filter

```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}}'
```

***

## Responses

<AccordionGroup>
  <Accordion title="200 - Successful response">
    ```json theme={null}
    {
      "pagination": {
        "limit": 10,
        "page": 1,
        "total": 1,
        "offset": 0,
        "totalPages": 1
      },
      "_metadata": {},
      "results": [
        {
          "recipient": {
            "id": "RECIPIENT_ID",
            "names": "Example Customer"
          },
          "sender": {
            "id": "BOT_ID",
            "name": "My Bot",
            "type": "WhatsApp"
          },
          "by": "bot",
          "messageId": "msg-12345-67890-4a38-abcde-fghij",
          "status": "DELIVERED_USER",
          "bubble": {
            "type": "TEXT",
            "text": "Hello, welcome to 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": ["The values entered are not correct."],
      "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>

***

## Response Detail

### pagination object

| Field          | Type    | Description                 |
| -------------- | ------- | --------------------------- |
| **limit**      | integer | Number of records per page. |
| **page**       | integer | Current page.               |
| **total**      | integer | Total records.              |
| **offset**     | integer | Offset from the beginning.  |
| **totalPages** | integer | Total available pages.      |

### results object

| Field         | Type   | Description                                                         |
| ------------- | ------ | ------------------------------------------------------------------- |
| **recipient** | object | Recipient information (id, names).                                  |
| **sender**    | object | Sender information (id, name, type).                                |
| **by**        | string | Indicates who sent the message: `bot` or `user`.                    |
| **messageId** | string | Unique message identifier.                                          |
| **status**    | string | Message status: `DELIVERED_USER`, `DELIVERED_CHANNEL`, `READ`, etc. |
| **bubble**    | object | Message content (type, text, mediaUrl, etc.).                       |
| **createdAt** | date   | Message creation date in ISO 8601 format.                           |

***

## Limits and restrictions

<Note>
  **Important limits:**

  * **limit**: Maximum allowed value is `50`
  * **page**: Must be a positive integer
  * **startAt/endAt**: Must be in ISO 8601 format (e.g.: `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

````