Adding docs for reports

openchatai · Jul 2, 2024 · 0fe73bf · 0fe73bf
1 parent 312d0d8
commit 0fe73bf
Show file tree

Hide file tree

Showing 13 changed files with 921 additions and 0 deletions.
diff --git a/docs/api-reference/endpoint/report/agent-activity.mdx b/docs/api-reference/endpoint/report/agent-activity.mdx
@@ -0,0 +1,82 @@
+---
+title: "Get Agent Activity"
+api: "GET https://api-v2.opencopilot.so/backend/reports/agents/activity"
+description: "Retrieve activity data for agents, including their active and open sessions within a specified time range."
+---
+
+This endpoint provides insights into agent activity, showing the number of active sessions and open sessions for each agent. It helps in monitoring agent workload and performance.
+
+### Query Parameters
+
+<ParamField query="startDate" type="string" format="date-time" optional>
+  The start date for the report period (ISO 8601 format). If not provided, defaults to the earliest possible date.
+</ParamField>
+
+<ParamField query="endDate" type="string" format="date-time" optional>
+  The end date for the report period (ISO 8601 format). If not provided, defaults to the current date and time.
+</ParamField>
+
+<ParamField query="copilot_id" type="string" optional>
+  Filter results for a specific copilot by ID.
+</ParamField>
+
+<ParamField query="limit" type="number" optional>
+  The maximum number of results to return. Defaults to the server's configured limit.
+</ParamField>
+
+<ParamField query="offset" type="number" optional>
+  The number of results to skip before starting to return data. Used for pagination.
+</ParamField>
+
+<ParamField query="sortOrder" type="string" optional>
+  The order to sort the results. Can be either 'asc' for ascending or 'desc' for descending.
+</ParamField>
+
+### Response
+
+<ResponseField name="agentId" type="number">
+  The unique identifier of the agent.
+</ResponseField>
+
+<ResponseField name="activeSessions" type="number">
+  The total number of active sessions handled by the agent within the specified time range.
+</ResponseField>
+
+<ResponseField name="openSessions" type="number">
+  The number of currently open sessions assigned to the agent.
+</ResponseField>
+
+### Example Request
+
+```bash
+curl --location --request GET 'https://api-v2.opencopilot.so/backend/reports/agents/activity?startDate=2023-01-01T00:00:00Z&endDate=2023-12-31T23:59:59Z&copilot_id=abc123' \
+--header 'Authorization: Bearer YOUR_API_KEY'
+```
+
+### Example Response
+
+```json
+[
+  {
+    "agentId": 1,
+    "activeSessions": 150,
+    "openSessions": 5
+  },
+  {
+    "agentId": 2,
+    "activeSessions": 120,
+    "openSessions": 3
+  },
+  {
+    "agentId": 3,
+    "activeSessions": 180,
+    "openSessions": 7
+  }
+]
+```
+
+This endpoint is useful for:
+- Monitoring agent workload and performance
+- Identifying agents who may need assistance or have capacity for more work
+- Analyzing patterns in agent activity over time
+```
diff --git a/docs/api-reference/endpoint/report/agent-performance.mdx b/docs/api-reference/endpoint/report/agent-performance.mdx
@@ -0,0 +1,78 @@
+---
+title: "Get Agent Performance"
+api: "GET https://api-v2.opencopilot.so/backend/reports/agents/performance"
+description: "Retrieve performance metrics for agents based on chat sessions"
+---
+
+This endpoint provides performance metrics for agents, including the total number of chats handled and the average duration of their chat sessions.
+
+### Query Parameters
+
+<ParamField query="startDate" type="string" format="date-time" optional>
+  The start date for the report period (ISO 8601 format)
+</ParamField>
+
+<ParamField query="endDate" type="string" format="date-time" optional>
+  The end date for the report period (ISO 8601 format)
+</ParamField>
+
+<ParamField query="copilot_id" type="string" optional>
+  Filter results by a specific copilot ID
+</ParamField>
+
+<ParamField query="limit" type="number" optional>
+  Limit the number of results returned
+</ParamField>
+
+<ParamField query="offset" type="number" optional>
+  Number of results to skip for pagination
+</ParamField>
+
+<ParamField query="sortOrder" type="string" optional>
+  Sort order for the results (asc or desc)
+</ParamField>
+
+### Response
+
+<ResponseField name="agentId" type="number">
+  The unique identifier of the agent
+</ResponseField>
+
+<ResponseField name="totalChats" type="number">
+  The total number of chats handled by the agent
+</ResponseField>
+
+<ResponseField name="avgDuration" type="number">
+  The average duration of chat sessions for the agent (in seconds)
+</ResponseField>
+
+<RequestExample>
+
+```bash Example Request
+curl --location --request GET 'https://api-v2.opencopilot.so/backend/reports/agents/performance?startDate=2023-01-01T00:00:00Z&endDate=2023-12-31T23:59:59Z&copilot_id=abc123' \
+--header 'Authorization: Bearer YOUR_API_KEY'
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+[
+  {
+    "agentId": 1,
+    "totalChats": 150,
+    "avgDuration": 420.5
+  },
+  {
+    "agentId": 2,
+    "totalChats": 120,
+    "avgDuration": 380.2
+  }
+]
+```
+
+</ResponseExample>
+
+
+This documentation provides a comprehensive overview of the agent performance endpoint, including its purpose, query parameters, response structure, and examples of both the request and response.
diff --git a/docs/api-reference/endpoint/report/agent-response-time.mdx b/docs/api-reference/endpoint/report/agent-response-time.mdx
@@ -0,0 +1,81 @@
+---
+title: "Get Agent Response Times"
+api: "GET https://api-v2.opencopilot.so/backend/reports/agents/response-times"
+description: "Retrieve average response times for agents in chat sessions"
+---
+
+This endpoint provides data on the average response times for agents in chat sessions. It helps analyze how quickly agents are responding to customer messages, which is crucial for assessing customer service efficiency.
+
+### Query Parameters
+
+<ParamField query="startDate" type="string" format="date-time">
+  The start date for the date range to analyze (ISO 8601 format)
+</ParamField>
+
+<ParamField query="endDate" type="string" format="date-time">
+  The end date for the date range to analyze (ISO 8601 format)
+</ParamField>
+
+<ParamField query="chatbot_id" type="string">
+  Filter results by a specific chatbot ID
+</ParamField>
+
+<ParamField query="session_id" type="string">
+  Filter results by a specific session ID
+</ParamField>
+
+<ParamField query="limit" type="number">
+  Limit the number of results returned
+</ParamField>
+
+<ParamField query="offset" type="number">
+  Number of results to skip (for pagination)
+</ParamField>
+
+<ParamField query="sortOrder" type="string">
+  Sort order for the results (asc or desc)
+</ParamField>
+
+### Response
+
+<ResponseField name="sessionId" type="string">
+  The unique identifier of the chat session
+</ResponseField>
+
+<ResponseField name="avgResponseTime" type="number">
+  The average response time for the agent in this session, in seconds
+</ResponseField>
+
+<RequestExample>
+
+```bash Example Request
+curl --location --request GET 'https://api-v2.opencopilot.so/backend/reports/agents/response-times?startDate=2023-01-01T00:00:00Z&endDate=2023-12-31T23:59:59Z&chatbot_id=abc123' \
+--header 'Accept: application/json' \
+--header 'Authorization: Bearer YOUR_TOKEN'
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+[
+  {
+    "sessionId": "session123",
+    "avgResponseTime": 45.5
+  },
+  {
+    "sessionId": "session456",
+    "avgResponseTime": 32.1
+  },
+  {
+    "sessionId": "session789",
+    "avgResponseTime": 60.3
+  }
+]
+```
+
+</ResponseExample>
+```
+
+This documentation provides a comprehensive overview of the "agents/response-times" endpoint, including its purpose, query parameters, response structure, and examples of both the request and response. The description explains that this endpoint is used to analyze agent response times, which is important for assessing customer service efficiency.
diff --git a/docs/api-reference/endpoint/report/chat-availability.mdx b/docs/api-reference/endpoint/report/chat-availability.mdx
@@ -0,0 +1,64 @@
+---
+title: "Get Chat Availability"
+api: "GET https://api-v2.opencopilot.so/backend/reports/chats/availability"
+description: "Retrieve the chat availability percentage for a specified time period"
+---
+
+### Query Parameters
+
+<ParamField query="startDate" type="string" required>
+  The start date for the report period (ISO 8601 format)
+</ParamField>
+
+<ParamField query="endDate" type="string" required>
+  The end date for the report period (ISO 8601 format)
+</ParamField>
+
+<ParamField query="copilot_id" type="string">
+  The ID of the copilot to filter results
+</ParamField>
+
+<ParamField query="channel" type="string">
+  The channel to filter results (e.g., "web", "mobile")
+</ParamField>
+
+<ParamField query="status" type="string">
+  The status to filter results (e.g., "open", "closed")
+</ParamField>
+
+<ParamField query="limit" type="number">
+  The maximum number of results to return
+</ParamField>
+
+<ParamField query="offset" type="number">
+  The number of results to skip before starting to return
+</ParamField>
+
+<ParamField query="sortOrder" type="string">
+  The order to sort the results ("asc" or "desc")
+</ParamField>
+
+### Response
+
+<ResponseField name="availability" type="number">
+  The availability percentage as a decimal between 0 and 1
+</ResponseField>
+
+<RequestExample>
+
+```bash Example Request
+curl --location --request GET 'https://api-v2.opencopilot.so/backend/reports/chats/availability?startDate=2023-01-01T00:00:00Z&endDate=2023-01-31T23:59:59Z&copilot_id=123456' \
+--header 'Authorization: Bearer YOUR_API_KEY'
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{
+  "availability": 0.985
+}
+```
+
+</ResponseExample>
diff --git a/docs/api-reference/endpoint/report/chat-duration.mdx b/docs/api-reference/endpoint/report/chat-duration.mdx
@@ -0,0 +1,51 @@
+---
+title: "Get Chat Duration"
+api: "GET https://api-v2.opencopilot.so/backend/reports/chats/duration"
+description: "Retrieve the average duration of chat sessions based on specified criteria"
+---
+
+### Query Parameters
+
+<ParamField query="startDate" type="string" format="date-time" optional>
+  The start date for the date range filter (ISO 8601 format)
+</ParamField>
+
+<ParamField query="endDate" type="string" format="date-time" optional>
+  The end date for the date range filter (ISO 8601 format)
+</ParamField>
+
+<ParamField query="copilot_id" type="string" optional>
+  Filter results by a specific copilot ID
+</ParamField>
+
+<ParamField query="channel" type="string" optional>
+  Filter results by a specific session channel
+</ParamField>
+
+<ParamField query="status" type="string" optional>
+  Filter results by a specific session status
+</ParamField>
+
+### Response
+
+<ResponseField name="averageDuration" type="number">
+  The average duration of chat sessions in seconds
+</ResponseField>
+
+### Example Request
+
+```bash
+curl --location --request GET 'https://api-v2.opencopilot.so/backend/reports/chats/duration?startDate=2023-01-01T00:00:00Z&endDate=2023-12-31T23:59:59Z&copilot_id=abc123'
+```
+
+### Example Response
+
+```json
+{
+  "averageDuration": 300.5
+}
+```
+
+This endpoint calculates the average duration of chat sessions based on the provided query parameters. It uses the difference between the `created_at` and `updated_at` timestamps of each session to determine the duration. The result is returned as an average in seconds.
+
+If no query parameters are provided, it will calculate the average duration for all chat sessions in the database. You can use the query parameters to filter the results by date range, copilot ID, channel, and status.