Skip to main content
GET
/
v1
/
external
/
messages
/
history
/
{botId}
Get Chat History
curl --request GET \
  --url https://api.jelou.ai/v1/external/messages/history/{botId} \
  --header 'Authorization: Basic <encoded-value>'
{
  "pagination": {
    "limit": 123,
    "page": 123,
    "total": 123,
    "offset": 123,
    "totalPages": 123
  },
  "_metadata": {},
  "results": [
    {
      "recipient": {
        "id": "<string>",
        "names": "<string>"
      },
      "sender": {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>"
      },
      "by": "bot",
      "messageId": "<string>",
      "status": "<string>",
      "bubble": {
        "type": "<string>",
        "text": "<string>",
        "mediaUrl": "<string>"
      },
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ]
}
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

FieldLocationTypeRequiredDescription
botIdPathstringYesUnique identifier of the bot whose history you want to query.

Query Parameters

FieldLocationTypeRequiredDefault valueDescription
limitQueryintegerNo10Number of messages to request. Maximum: 50.
pageQueryintegerNo1Page number.
startAtQuerydateNo-Start date of the range to query. ISO 8601 format.
endAtQuerydateNo-End date of the range to query. ISO 8601 format.
clientIdQuerystringNo-Filters the history by a specific clientId associated with your integrations.
messageIdQuerystringNo-Returns the conversation that contains the message with this identifier.
If you omit optional fields, the API will apply default values to deliver the first page with the most recent messages.

Request Examples

Basic query

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

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

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

{
  "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"
    }
  ]
}
{
  "message": "Authentication failed"
}
{
  "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."
    }
  }
}
{
  "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"
      }
    ]
  }
}
{
  "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."
    }
  }
}

Response Detail

pagination object

FieldTypeDescription
limitintegerNumber of records per page.
pageintegerCurrent page.
totalintegerTotal records.
offsetintegerOffset from the beginning.
totalPagesintegerTotal available pages.

results object

FieldTypeDescription
recipientobjectRecipient information (id, names).
senderobjectSender information (id, name, type).
bystringIndicates who sent the message: bot or user.
messageIdstringUnique message identifier.
statusstringMessage status: DELIVERED_USER, DELIVERED_CHANNEL, READ, etc.
bubbleobjectMessage content (type, text, mediaUrl, etc.).
createdAtdateMessage creation date in ISO 8601 format.

Limits and restrictions

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)

Authorizations

Authorization
string
header
required

Basic authentication using Base64 encoded clientId:clientSecret

Path Parameters

botId
string
required

Query Parameters

limit
integer
default:10
Required range: x <= 50
page
integer
default:1
startAt
string<date-time>
endAt
string<date-time>
clientId
string
messageId
string

Response

History retrieved successfully

pagination
object
_metadata
object
results
object[]