> ## 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.
# Agent conversations
> Query conversations handled by human agents
Retrieve conversations attended by a human agent to analyze response times, closure states, and assignments. You receive metadata about operators, users, and bots involved within a defined date range.
***
## Endpoint
```
POST https://api.jelou.ai/v1/metrics/conversations/attended/external
```
***
## Authentication
| Field | Location | Type | Required | Description |
| ----------------- | -------- | ------ | -------- | ---------------------------------------------- |
| **Authorization** | Header | string | Yes | Credentials in `clientId:clientSecret` format. |
***
## Query Parameters
| Field | Location | Type | Required | Default value | Description |
| --------- | -------- | ------- | -------- | ------------- | ----------------------------------------- |
| **limit** | Query | integer | No | 10 | Maximum number of conversations per page. |
| **page** | Query | integer | No | 1 | Page number for pagination. |
***
## Request Body
| Field | Type | Required | Description |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------- |
| **startAt** | string | Yes | Start date of the range in ISO 8601 format. Example: `2025-01-01T00:00:00-05:00` |
| **endAt** | string | Yes | End date of the range in ISO 8601 format. Example: `2025-01-01T23:59:59-05:00` |
| **getJson** | boolean | Yes | Must be `true` to receive the response in JSON format. |
Use bounded time windows to optimize the query and avoid overly wide ranges if you handle high volumes of conversations.
***
## Request Examples
```bash theme={null}
curl -X POST 'https://api.jelou.ai/v1/metrics/conversations/attended/external?limit=10' \
-H 'Authorization: :' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"startAt": "2025-01-01T00:00:00-05:00",
"endAt": "2025-01-01T23:59:59-05:00",
"getJson": true
}'
```
```javascript theme={null}
const axios = require('axios');
axios({
method: 'POST',
url: 'https://api.jelou.ai/v1/metrics/conversations/attended/external',
params: { limit: 10 },
headers: {
'Content-Type': 'application/json;charset=UTF-8',
'Authorization': ':'
},
data: {
startAt: '2025-01-01T00:00:00-05:00',
endAt: '2025-01-01T23:59:59-05:00',
getJson: true
}
});
```
***
## Responses
```json theme={null}
{
"message": ["Retrieving conversations succeeded"],
"status": "success",
"results": [
{
"_id": "CONVERSATION_ID",
"operator": {
"names": "OPERATOR_NAME"
},
"user": {
"id": "ID"
},
"bot": {
"name": "BOT_NAME"
},
"company": {
"id": "COMPANY_ID"
},
"assignationMethod": {
"teamName": "TEAM_NAME"
},
"state": "expired",
"endedReason": "expired",
"startAt": "2023-06-08 15:52:41",
"endAt": "2023-06-08 23:07:56",
"origin": "ticket",
"timeRepliedOperator": 795880,
"conversationDuration": 26115953
}
],
"pagination": {
"limit": 1,
"total": 61,
"offset": 0,
"totalPages": 61
},
"links": [
{
"number": 1,
"url": "/v1/metrics/conversations/attended/external?limit=1&page=1"
},
{
"number": 2,
"url": "/v1/metrics/conversations/attended/external?limit=1&page=2"
}
]
}
```
```json theme={null}
{
"message": "Authentication failed"
}
```
```json theme={null}
{
"message": ["The values entered are not correct."],
"statusMessage": "failed",
"status": 0,
"error": {
"code": "E0422",
"key": "VALIDATOR_ERROR"
}
}
```
```json theme={null}
{
"message": "Rate limit exceeded"
}
```
```json theme={null}
{
"message": ["We are having trouble processing your request. Please try again later."],
"statusMessage": "failed",
"status": 0
}
```
***
## Response Detail
### results object
| Field | Type | Description |
| ------------------------ | ------ | ----------------------------------------------------------------------- |
| **\_id** | string | Unique conversation identifier. |
| **operator** | object | Information about the operator who attended the conversation (`names`). |
| **user** | object | User information (`id`). |
| **bot** | object | Associated bot information (`name`). |
| **company** | object | Company information (`id`). |
| **assignationMethod** | object | Assignment method and team (`teamName`). |
| **state** | string | Conversation state: `active`, `closed`, `resolved`, `expired`. |
| **endedReason** | string | Reason why the conversation ended. |
| **startAt** | string | Conversation start date and time. |
| **endAt** | string | Conversation end date and time. |
| **origin** | string | Conversation source (e.g.: `ticket`). |
| **timeRepliedOperator** | number | Operator response time in milliseconds. |
| **conversationDuration** | number | Total conversation duration in milliseconds. |
### pagination object
| Field | Type | Description |
| -------------- | ------- | ------------------------------------------------------ |
| **limit** | integer | Conversations returned per page. |
| **total** | integer | Total conversations matching the filters. |
| **offset** | integer | Conversations skipped according to the requested page. |
| **totalPages** | integer | Total number of available pages. |
### links object
| Field | Type | Description |
| ---------- | ------- | --------------------------------- |
| **number** | integer | Page number. |
| **url** | string | Relative URL to access that page. |
***
## Performance metrics
Use the `timeRepliedOperator` and `conversationDuration` fields to analyze the efficiency of your support team:
* **timeRepliedOperator**: Measures the time it takes an agent to give the first response (in milliseconds).
* **conversationDuration**: Measures the total duration from the start to the close of the conversation (in milliseconds).
## OpenAPI
````yaml POST /v1/metrics/conversations/attended/external
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/metrics/conversations/attended/external:
post:
tags:
- Conversations
summary: Get Advisor Conversations
description: Retrieve conversations attended by human advisors within a date range.
operationId: getAdvisorConversations
parameters:
- name: limit
in: query
schema:
type: integer
default: 10
- name: page
in: query
schema:
type: integer
default: 1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdvisorConversationsRequest'
responses:
'200':
description: Conversations retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AdvisorConversationsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
description: Rate limit exceeded
components:
schemas:
AdvisorConversationsRequest:
type: object
required:
- startAt
- endAt
- getJson
properties:
startAt:
type: string
format: date-time
endAt:
type: string
format: date-time
getJson:
type: boolean
AdvisorConversationsResponse:
type: object
properties:
message:
type: array
items:
type: string
status:
type: string
results:
type: array
items:
$ref: '#/components/schemas/AdvisorConversation'
pagination:
$ref: '#/components/schemas/Pagination'
links:
type: array
items:
type: object
AdvisorConversation:
type: object
properties:
_id:
type: string
operator:
type: object
properties:
names:
type: string
user:
type: object
properties:
id:
type: string
bot:
type: object
properties:
name:
type: string
company:
type: object
properties:
id:
type: string
assignationMethod:
type: object
properties:
teamName:
type: string
state:
type: string
enum:
- active
- closed
- resolved
- expired
endedReason:
type: string
startAt:
type: string
endAt:
type: string
origin:
type: string
timeRepliedOperator:
type: integer
conversationDuration:
type: integer
Pagination:
type: object
properties:
limit:
type: integer
page:
type: integer
total:
type: integer
offset:
type: integer
totalPages:
type: integer
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'
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
````