{
  "openapi": "3.1.0",
  "info": {
    "title": "bitbybit Analytics API",
    "description": "Retrieve CS & ticket performance analytics per company through the bitbybit Open API.",
    "version": "1.0.0",
    "contact": {
      "name": "bitbybit Support",
      "url": "https://bitbybit.studio"
    }
  },
  "servers": [
    {
      "url": "https://api.bitbybit.studio/whatsapp/open/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/analytics/agents": {
      "get": {
        "operationId": "getAgentAnalytics",
        "summary": "Get agent performance analytics",
        "description": "Returns aggregated CS & ticket performance metrics per agent (both human and AI) for the company associated with the API key, over the requested time window.\n\nThe `company_id` is implicit — it is derived from the API key. To query multiple companies, call this endpoint once per API key.",
        "tags": [
          "Analytics"
        ],
        "parameters": [
          {
            "name": "startAt",
            "in": "query",
            "required": true,
            "description": "Start of the reporting window (ISO 8601). Inclusive.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-07-20T00:00:00Z"
          },
          {
            "name": "endAt",
            "in": "query",
            "required": true,
            "description": "End of the reporting window (ISO 8601). Inclusive.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-07-20T23:59:59Z"
          },
          {
            "name": "sources",
            "in": "query",
            "required": false,
            "description": "Optional channel filter. Accepts a single value. To combine channels, call the endpoint per channel and merge on your side.",
            "schema": {
              "type": "string",
              "enum": [
                "whatsapp",
                "whatsapp_cloud_api",
                "whatsapp_coex",
                "instagram",
                "facebook",
                "tiktok",
                "outlook",
                "widget"
              ]
            },
            "example": "whatsapp_cloud_api"
          },
          {
            "name": "agentName",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring match on the agent display name.",
            "schema": {
              "type": "string"
            },
            "example": "Tika"
          }
        ],
        "responses": {
          "200": {
            "description": "Analytics records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "range": {
                          "type": "object",
                          "properties": {
                            "start_at": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "end_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "records": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/AgentAnalyticsRecord"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "status": "success",
                  "data": {
                    "range": {
                      "start_at": "2026-07-20T00:00:00Z",
                      "end_at": "2026-07-20T23:59:59Z"
                    },
                    "records": [
                      {
                        "company_id": 1646,
                        "agent_id": 12,
                        "agent_name": "Bu Tika",
                        "agent_type": "human",
                        "tickets_handled": 45,
                        "first_response_time": "00:04:12",
                        "avg_response_time": "00:06:06",
                        "resolution_time": "03:30:00",
                        "last_chat_handled": "2026-07-20T17:42:00Z"
                      },
                      {
                        "company_id": 1646,
                        "agent_id": -2,
                        "agent_name": "AI Agent",
                        "agent_type": "ai",
                        "tickets_handled": 210,
                        "first_response_time": "00:00:06",
                        "avg_response_time": "00:00:18",
                        "resolution_time": "00:00:48",
                        "last_chat_handled": "2026-07-20T18:12:00Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key for authentication. Create one in Settings > Developer with the Analytics READ scope."
      }
    },
    "schemas": {
      "AgentAnalyticsRecord": {
        "type": "object",
        "properties": {
          "company_id": {
            "type": "integer",
            "description": "Company the API key belongs to."
          },
          "agent_id": {
            "type": "integer",
            "description": "Internal user id. `-2` is the AI agent; positive values are human agents."
          },
          "agent_name": {
            "type": "string"
          },
          "agent_type": {
            "type": "string",
            "enum": ["human", "ai"]
          },
          "tickets_handled": {
            "type": "integer",
            "description": "Number of tickets this agent handled in the window."
          },
          "first_response_time": {
            "type": "string",
            "description": "Average first response time in `HH:MM:SS`."
          },
          "avg_response_time": {
            "type": "string",
            "description": "Average response time in `HH:MM:SS`."
          },
          "resolution_time": {
            "type": "string",
            "description": "Average resolution time in `HH:MM:SS`."
          },
          "last_chat_handled": {
            "type": "string",
            "nullable": true,
            "description": "Timestamp of the most recent chat this agent handled (ISO 8601)."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "INVALID_API_KEY",
                "message": "Invalid or expired API key"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Insufficient permissions",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "INSUFFICIENT_SCOPE",
                "message": "API key does not have the analytics:READ scope"
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "Validation error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "VALIDATION_ERROR",
                "message": "startAt must be a valid ISO 8601 date-time"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "RATE_LIMIT_EXCEEDED",
                "message": "Too many requests. Please retry after the reset period."
              }
            }
          }
        }
      }
    }
  }
}