> For the complete documentation index, see [llms.txt](https://shillbot.gitbook.io/shillbot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shillbot.gitbook.io/shillbot/getting-started/publish-your-docs.md). # API Reference ## Create Bot **Endpoint** `POST /v1/bots` #### Description This endpoint allows you to create a new bot in the system. It requires specific parameters in the request body and query string, and upon successful creation, it will return the details of the newly created bot. #### Authentication * This endpoint requires bearer token authentication. * Users must be authorized with the appropriate permissions to create a bot. #### Request **Headers** ``` Authorization: Bearer or x-api-key: Content-Type: application/json ``` **Query Parameters** * `appId` (string, required): The ID of the application to which the bot will be associated. **Request Body** The request body must be a JSON object that conforms to the `BotCreateDTO` structure: ``` { "username": "exampleBot", "password": "securePassword", "mail": "bot@example.com", "phone": "1234567890", "appAuthSecret": "secretKey123", "blueTick": false } ``` #### Response **Success Response** On successful creation, the response will return a `BotCreateResDTO` structure that contains the bot's details: ``` { "data": { "id": "1728b82b-a338-4d34-af85-7a8695941ffd", "status": "ACTIVE", "errorMessage": null, "createdBy": "USER", "follower": null, "following": null, "username": "exampleBot", "mail": "bot@example.com", "phone": "1234567890", "proxyId": "proxy-id-123", "blueTick": false, "appAuthSecret": "secretKey123", "taskCount": 0, "profile": { "id": "profile-id-123", "createdAt": "2024-09-17T09:21:13.634Z", "updatedAt": "2024-10-02T02:34:27.148Z", "state": "DONE", "bio": null, "name": null, "banner": null, "avatar": null, "website": null }, "histories": [], "createdAt": "2024-09-17T09:21:13.634Z" }, "message": "success", "statusCode": 200 } ``` **Error Responses** * **400 Bad Request**: If the request is malformed or required parameters are missing. ``` { "statusCode": 400, "message": "Validation failed", "error": "Bad Request" } ``` * **401 Unauthorized**: If the user is not authenticated or does not have the necessary permissions. ``` { "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" } ``` #### Example Usage Here is an example of how to call the endpoint using `curl`: ``` curl -X POST "https://api.shillbot.xyz/v1/bots?appId=yourAppId" \ -H "Authorization: Bearer your_token" \ -H "Content-Type: application/json" \ -d '{ "username": "exampleBot", "password": "securePassword", "mail": "bot@example.com", "phone": "1234567890", "proxyId": "proxy-id-123", "appAuthSecret": "secretKey123", "blueTick": false }' ``` #### Notes * Ensure that the `username` is unique and meets any constraints specified by your application. * The `appAuthSecret` is sensitive and should be treated securely. * Review the expected field types in the request body to ensure proper validation. ## List Bot **Endpoint** **GET** `/v1/bots` **Description** This endpoint retrieves a paginated list of bots in the system based on specified query parameters. It provides information about each bot, including its status, username, email, and other relevant details. **Authentication** This endpoint requires bearer token authentication. Users must be authorized with the appropriate permissions to access the bot list. **Request** #### Headers ``` Authorization: Bearer or x-api-key: ``` #### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------------------------------------------- | | appId | string | Yes | The ID of the application to which the bots belong. | | limit | number | No | The number of results to return per page. Default is `10`. | | offset | number | No | The number of items to skip before starting to collect the result set. Default is `0`. | | botState | string | No | The state of the bots to filter by (e.g., ACTIVE). | | search | string | No | A search term to filter bots by their username, email, etc. | | isDeleted | string | No | To filter bots based on their deletion status (e.g., `true` or `false`). | Example Request ``` GET https://api.shillbot.xyz/v1/bots?appId=yourAppId&limit=30&offset=0&botState=ACTIVE Authorization: Bearer or x-api-key: ``` **Response** #### Success Response On a successful request, the response will return a `BotPagingResDTO` structure containing a paginated list of bots: ``` { "data": { "total": 9, "data": [ { "status": "ACTIVE", "errorMessage": nu, "createdBy": "USER", "follower": null, "following": null, "username": "username", "mail": "email@example.com", "phone": "0335845350", "proxyId": "140d0ca9-60e2-404f-862e-eb6462f16474", "blueTick": false, "appAuthSecret": "appAuthSecret", "taskCount": 2, "profile": { "id": "843f9ad7-40f4-4d7b-8e8d-aecce93d9951", "createdAt": "2024-09-17T09:21:13.634Z", "updatedAt": "2024-10-02T02:34:27.148Z", "state": "DONE", "bio": null, "name": null, "banner": null, "avatar": null, "website": null }, "histories": [], "id": "1728b82b-a338-4d34-af85-7a8695941ffd", "createdAt": "2024-09-17T09:17:36.276Z" }, ... ], "active": 9, "isProfileUpdating": [] }, "path": "/v1/bots?limit=30&appId=fd8e0a24-f5de-4736-834d-9388f00e48eb&offset=0&botState=ACTIVE&endDate=2024-10-05T23:59:59.999Z&startDate=2024-10-05T00:00:00.000Z", "method": "GET", "message": "success", "statusCode": 200 } ``` #### Error Responses * **400 Bad Request**: If the request is malformed or required parameters are missing. ``` { "statusCode": 400, "message": "Validation failed", "error": "Bad Request" } ``` * **401 Unauthorized**: If the user is not authenticated or does not have the necessary permissions. ``` { "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" } ``` #### Example Usage Here is an example of how to call the endpoint using curl: ``` curl -X GET "https://api.shillbot.xyz/v1/bots?appId=yourAppId&limit=30&offset=0&botState=ACTIVE" \ -H "Authorization: Bearer your_token" ``` #### Notes * Adjust the `limit` and `offset` parameters to paginate through results. * The `botState` parameter can be used to filter results based on the bot's current status. * Ensure that the `appId` corresponds to a valid application in your system. #### Explanation of Main Fields 1. **data**: This is the main object containing the response details related to the bots. * **total**: * Type: Integer * Description: The total number of bot records available that match the query. In this case, it indicates there are 9 bots in total. * **data**: * Type: Array of Bot Objects * Description: An array of bot records that match the filtering criteria. Each object contains detailed information about an individual bot. * **active**: * Type: Integer * Description: The number of bots that are currently in an "ACTIVE" state. This indicates that there are 9 active bots in the current context. * **isProfileUpdating**: * Type: Array * Description: An empty array in this context. It might be intended to hold information about bots whose profiles are currently being updated, if applicable. 2. **path**: * Type: String * Description: The API endpoint path that was accessed, including the query parameters used in the request. 3. **method**: * Type: String * Description: The HTTP method used for the request (GET in this case). 4. **message**: * Type: String * Description: A brief description of the result of the API call (e.g., "success" indicates that the request was processed successfully). 5. **statusCode**: * Type: Integer * Description: The HTTP status code returned by the server. A value of 200 indicates that the request was successful. #### Breakdown of Each Bot Object in the Data Array Now, let's delve deeper into the fields of each bot object within the `data` array: ``` { "status": "ACTIVE", "errorMessage": "EXPIRE_SESSION", "createdBy": "USER", "follower": null, "following": null, "username": "username", "mail": "email@example.com", "phone": "0335845350", "proxyId": "140d0ca9-60e2-404f-862e-eb6462f16474", "blueTick": false, "appAuthSecret": "appAuthSecret", "taskCount": 2, "profile": { ... }, "histories": [ ... ], "id": "1728b82b-a338-4d34-af85-7a8695941ffd", "createdAt": "2024-09-17T09:17:36.276Z" } ``` #### **Field Descriptions** | Field | Type | Description | | -------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **status** | string | The current status of the bot. It indicates whether the bot is active, locked, or in another state. | | **errorMessage** | string (or null) | An error message associated with the bot, providing insights into issues that may affect its operation. For instance, `"EXPIRE_SESSION"` suggests session expiration. | | **createdBy** | string | Indicates who created the bot (e.g., `"USER"` means it was created by a user, as opposed to the system). | | **follower** | integer (or null) | The number of followers the bot has. It can be null if this information is not available. | | **following** | integer (or null) | The number of accounts the bot is following. It can be null if this information is not available. | | **username** | string | The unique username of the bot used in interactions. | | **mail** | string (or null) | The email address associated with the bot, which can be used for notifications or recovery. | | **phone** | string | The phone number associated with the bot, used for two-factor authentication or other communication purposes. | | **proxyId** | string | Identifier for the proxy server associated with the bot, if applicable. | | **blueTick** | boolean | Indicates whether the bot has a verified status (blue tick) on the platform it operates (e.g., Twitter). | | **appAuthSecret** | string | A secret key used for authenticating the bot with the application. This is sensitive information and should be kept secure. | | **taskCount** | integer | The number of tasks currently assigned to the bot. | | **profile** | object | Contains detailed profile information about the bot, including fields such as `id`, `createdAt`, `updatedAt`, and any relevant profile details like `bio`, `name`, `banner`, `avatar`, and `website`. | | **histories** | array of objects | An array containing the history of interactions or events related to the bot. Each history entry includes: | | **histories.id** | string | Unique identifier for the history record. | | **histories.createdAt** | datetime | Timestamp for when the history entry was created. | | **histories.updatedAt** | datetime | Timestamp for when the history entry was last updated. | | **histories.type** | string | The type of interaction (e.g., `"BOT_INTERACTION"`). | | **interactionBot.id** | string | Unique identifier for the interaction associated with the bot. | | **interactionBot.url** | string (or null) | URL associated with the interaction, if applicable. | | **interactionBot.type** | string | Type of interaction (e.g., `"FOLLOW"`). | | **interactionBot.state** | string | Current state of the interaction (e.g., `"ERROR"`). | | **interactionBot.error** | string (or null) | Specific error message related to the interaction, if any. | | **interactionBot.origin** | string (or null) | The origin URL associated with the interaction. | | **interactionBot.createdAt** | datetime | Timestamp indicating when the interaction was created. | | **interactionBot.updatedAt** | datetime | Timestamp indicating when the interaction was last updated. | | **interactionBot.interactionAt** | datetime | Timestamp tracking when the interaction occurred. | | **id** | string | Unique identifier for the bot. | | **createdAt** | datetime | Timestamp indicating when the bot was created. | #### **BOT\_STATUS Enum Breakdown** | Status | Description | Use Case | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **ERROR** | This status indicates that the bot has encountered an error that prevents it from functioning correctly. This could be due to network issues, authentication failures, or other critical errors. | The bot may need to be reviewed or restarted by a user or administrator to resolve the underlying issue. | | **ACTIVE** | The bot is currently operational and functioning as intended. It is actively performing tasks or interacting with users on the platform. | Users can expect the bot to behave normally, performing tasks like posting updates or interacting with users. | | **LOCKED** | The bot has been locked, likely due to security concerns, platform policy violations, or manual intervention by an administrator. | The bot cannot perform any actions until unlocked. Review activities to ensure compliance with platform rules. | | **WAITING** | The bot is in a waiting state, ready to execute tasks once certain conditions are met (e.g., waiting for user input, a scheduled time, or resource availability). | Used during transitions or when the bot is waiting for further instructions before proceeding. | | **LOGGING** | The bot is in the process of logging in or authenticating with a service. This state is temporary and should change to either **ACTIVE** or **ERROR** depending on the success of the login process. | Monitor authentication attempts to determine if the bot successfully connects to the platform it interacts with. | | **SUSPENDED** | The bot is temporarily suspended from activity, possibly due to concerns or violations. It may require review before becoming active again. | A suspended bot may need user intervention or a review process before it can be reinstated to **ACTIVE** status. | | **PROXY\_FAILED** | The bot was unable to connect to or utilize the proxy server it relies on. This failure can hinder the bot's ability to perform tasks requiring internet access. | Users should check the proxy configuration and ensure the proxy server is reachable and operational. | | **LOGIN\_CODE\_REQUEST** | The bot is waiting for a login code, typically required for two-factor authentication (2FA). This state persists until the user provides the necessary code. | The bot needs user intervention to retrieve and input the 2FA code to proceed with operations. | *** #### **BOT\_ERROR\_MESSAGE Enum Breakdown** | Error Message | Description | Use Case | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | **AUTHENTICATION\_REQUIRED** | This error indicates that the bot is unable to authenticate with the platform or service. This could be due to missing or invalid credentials (e.g., username/password). | Prompts users to ensure the bot has correct authentication credentials and permissions to access the required resources. | | **PROXY\_FAILED** | This error indicates that the bot could not connect to the specified proxy server, possibly due to incorrect configuration or network issues. | Users should verify the proxy settings and ensure the proxy server is operational. Manual testing may be required. | | **EXPIRE\_SESSION** | This error indicates that the bot’s session has expired, often due to inactivity or expired authentication tokens. | Users may need to re-authenticate or refresh tokens to restore the bot's functionality. | | **INVALID\_ACCOUNT** | This error signifies that the account being used by the bot is invalid or no longer exists (e.g., deleted account or credential typos). | Users should verify the account details to ensure they are correct and that the account is active and valid. | | **BOT\_INACTIVE** | This error indicates that the bot is not active and unable to perform its tasks. It might have been deactivated or suspended by the platform. | Users should investigate the reason for the bot's inactivity and take actions to reactivate it, if necessary. | | **ACCOUNT\_WAS\_LOCKED** | This error message indicates that the account associated with the bot has been locked, possibly due to suspicious activity or policy violations. | Users need to review the account status and may need to contact support to unlock the account before the bot can operate. | | **LOGIN\_CODE\_REQUEST** | This error occurs when the bot is waiting for a login code, typically required for two-factor authentication (2FA). | Users should retrieve and input the 2FA code sent to their device or email to allow the bot to continue its operation. | *** ## Delete Bot By ID **Description** This endpoint allows you to delete (revoke) a bot from the system. The bot will be permanently removed, and the relevant data will no longer be accessible. The API call requires an authorized user with the appropriate permissions to delete a bot. **Request** * **URL**: ```bash DELETE https://api.shillbot.xyz/v1/bots/{botId}/revoke?appId={appId} ``` * **Method**: `DELETE` * **Authentication**: This endpoint requires bearer token authentication or API key authentication. * Headers: * `Authorization: Bearer ` or `x-api-key: ` * `Content-Type: application/json` * **Query Parameters**: * `appId` (string, required): The ID of the application to which the bot is associated. * **Path Parameters**: * `botId` (string, required): The unique identifier of the bot to be deleted. Replace `{botId}` in the URL with the actual bot ID. **Example Request** ``` curl -X DELETE "https://api.shillbot.xyz/v1/bots/310e4072-796f-4ef4-bd48-96e58a4082e3/revoke?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb" \ -H "Authorization: Bearer your_token" \ -H "Content-Type: application/json" ``` **Response** On successful deletion, the response will return a JSON object with details about the bot that was deleted. * **Status Code**: `200 OK` * **Response Body**: ``` { "data": { "follower": null, "username": "username", "id": "310e4072-796f-4ef4-bd48-96e58a4082e3" }, "path": "/v1/bots/310e4072-796f-4ef4-bd48-96e58a4082e3/revoke?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb", "method": "DELETE", "message": "success", "statusCode": 200 } ``` **Error Responses** * **401 Unauthorized**: If the user is not authenticated or does not have the required permissions to delete the bot. **Notes** * Make sure the `botId` is valid and the user has the necessary permissions to delete the bot. * The `appId` should correspond to the application associated with the bot. ## Refresh Bot API **Description** This endpoint allows you to refresh a bot's session in case of an expired session, login errors, or other session-related issues. It updates the bot’s authentication details and ensures that the bot is logged in again successfully. This is particularly useful when a bot encounters a session expiration error. **Request** * **URL**: ``` PUT https://api.shillbot.xyz/v1/bots/{botId}?appId={appId} ``` * **Authentication**: This endpoint requires bearer token authentication or API key authentication. * Headers: * `Authorization: Bearer ` or `x-api-key: ` * `Content-Type: application/json` * **Query Parameters**: * `appId` (string, required): The ID of the application to which the bot is associated. * **Path Parameters**: * `botId` (string, required): The unique identifier of the bot to be refreshed. Replace `{botId}` in the URL with the actual bot ID. * **Request Body**: The request body must include the updated status of the bot. ``` { "status": "WAITING" } ``` **Example Request** ``` curl -X PUT "https://api.shillbot.xyz/v1/bots/42528b39-6349-4b08-b9ea-7105fa3ecbf4?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb" \ -H "Authorization: Bearer your_token" \ -H "Content-Type: application/json" \ -d '{ "status": "WAITING" }' ``` **Response** On a successful update, the response will return the updated details of the bot. * **Status Code**: `200 OK` ## Create Task Endpoint: #### **POST** `/v1/tasks` **Description** This endpoint allows users to create a new task in the system. It requires specific parameters in the request body and query string. Upon successful creation, it will return the details of the newly created task. #### **Authentication** This endpoint requires bearer token authentication. Users must be authorized with the appropriate permissions to create a task. #### **Request Headers** * `Authorization: Bearer ` or `x-api-key: ` * `Content-Type`: application/json #### **Query Parameters** | Name | Type | Required | Description | | ----- | ------ | -------- | --------------------------------------------------------------- | | appId | string | Yes | The ID of the application to which the task will be associated. | #### **Request Body** The request body must be a JSON object that conforms to the `TaskCreateDTO` structure: ``` { "title": "test", "categoryId": "c16c5afb-1992-4894-b9fd-e1721d4a4517", "postPerDay": 10, "botIds": [ "1728b82b-a338-4d34-af85-7a8695941ffd", "1a1664e7-c90c-4498-a9a2-3755102cf410" ], "customerGroupIds": [ "068ece90-f1db-4402-84c0-e5a5fa0be585" ], "type": "USERS", "templateContents": [ "content", "content" ] } ``` #### **Field Descriptions** | Field | Type | Required | Description | | ------------------ | ---------------- | -------- | --------------------------------------------------------------- | | `title` | `string` | Yes | The title of the task being created. | | `categoryId` | `string` | Yes | The ID of the category to which the task belongs. | | `postPerDay` | `number` | Yes | The number of posts to be made per day for the task. | | `botIds` | `string[]` | Yes | An array of bot IDs associated with the task. | | `customerGroupIds` | `string[]` | Yes | An array of customer group IDs associated with the task. | | `type` | `TASK_TYPE` enum | Yes | The type of task (e.g., USERS, POSTS, KEYWORDS, USER\_KEYWORDS) | | | | | | | `templateContents` | `string[]` | Yes | An array of template content strings used for the task. | #### **Response** On successful creation, the response will return a JSON object structured as follows: **Success Response** ``` { "data": { "type": "USERS", "status": "RUNNING", "title": "test", "categoryId": "c16c5afb-1992-4894-b9fd-e1721d4a4517", "templateId": "345450c6-7a58-47f4-9973-4e18bf3e2d6a", "posts": [], "images": [], "keywords": [], "keywordAddTagIds": [], "keywordAddGroupIds": [], "id": "6df3b700-797e-44dc-9adc-1f3751969df8" }, "path": "/v1/tasks?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb", "method": "POST", "message": "success", "statusCode": 200 } ``` #### **Field Descriptions** | Field | Type | Description | | ------------------------- | -------- | ---------------------------------------------------------------- | | `data` | `object` | The main response object containing the task details. | | `data.type` | `string` | The type of the task (e.g., "USERS"). | | `data.status` | `string` | The current status of the task (e.g., "RUNNING"). | | `data.title` | `string` | The title of the task being created. | | `data.categoryId` | `string` | The ID of the category to which the task belongs. | | `data.templateId` | `string` | The ID of the template associated with the task. | | `data.posts` | `array` | An array of post IDs associated with the task (initially empty). | | `data.images` | `array` | An array of images associated with the task (initially empty). | | `data.keywords` | `array` | An array of keywords associated with the task (initially empty). | | `data.keywordAddTagIds` | `array` | An array of tag IDs to add to keywords (initially empty). | | `data.keywordAddGroupIds` | `array` | An array of group IDs to add to keywords (initially empty). | | `data.id` | `string` | The unique ID of the created task. | | `path` | `string` | The endpoint path used for the request. | | `method` | `string` | The HTTP method used for the request (e.g., "POST"). | | `message` | `string` | A success message indicating the task creation was successful. | | `statusCode` | `number` | The HTTP status code of the response (200 indicates success). | #### **Error Responses** | Status Code | Description | Example Response | | ---------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | 400 Bad Request | If the request is malformed or required parameters are missing. | `{ "statusCode": 400, "message": "Validation failed", "error": "Bad Request" }` | | 401 Unauthorized | If the user is not authenticated or does not have the necessary permissions. | `{ "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" }` | #### **Example Usage** Here is an example of how to call the endpoint using `curl`: ``` curl -X POST "https://api.shillbot.xyz/v1/tasks?appId=yourAppId" \ -H "Authorization: Bearer your_token" \ -H "Content-Type: application/json" \ -d '{ "title": "test", "categoryId": "c16c5afb-1992-4894-b9fd-e1721d4a4517", "postPerDay": 10, "botIds": [ "1728b82b-a338-4d34-af85-7a8695941ffd", "1a1664e7-c90c-4498-a9a2-3755102cf410" ], "customerGroupIds": [ "068ece90-f1db-4402-84c0-e5a5fa0be585" ], "type": "USERS", "templateContents": [ "content" ] }' ``` #### **Notes** * Ensure that the `appId` is valid and the user has the necessary permissions for the application. * Review the expected field types in the request body to ensure proper validation. ## Get List of Running Tasks **GET** `/v1/tasks` **Description** This endpoint retrieves a paginated list of tasks that are currently running. Users can filter tasks based on various criteria, such as task type, status, category IDs, and search terms. #### **Request Headers** * `Authorization: Bearer ` or `x-api-key: ` * `Content-Type`: application/json #### **Query Parameters** | Name | Type | Required | Description | | ------------- | --------- | -------- | ----------------------------------------------------------------------------------------- | | `appId` | string | Yes | The ID of the application associated with the tasks. | | `limit` | number | No | The maximum number of tasks to return (default is 10). | | `offset` | number | No | The number of tasks to skip before starting to collect the result set (default is 0). | | `search` | string | No | A search string to filter tasks based on title or other criteria. | | `categoryIds` | string\[] | No | An array of category IDs to filter the tasks by specific categories. | | `type` | string | No | The type of the tasks to filter (must be one of the defined `TASK_TYPE` enum values). | | `status` | string | No | The status of the tasks to filter (must be one of the defined `TASK_STATUS` enum values). | | `isDeleted` | string | No | To filter tasks based on their deletion status (if applicable). | #### **Response** On successful retrieval, the response will return a JSON object structured as follows: Success Response ``` { "data": { "data": [ { "id": "6df3b700-797e-44dc-9adc-1f3751969df8", "type": "USERS", "title": "test", "status": "RUNNING", "categoryId": "c16c5afb-1992-4894-b9fd-e1721d4a4517", "templateId": "345450c6-7a58-47f4-9973-4e18bf3e2d6a", "posts": [], "images": [], "keywords": [], "keywordAddTagIds": [], "keywordAddGroupIds": [], "botIds": [], "customerGroupIds": [], "includeCustomerTagIds": [], "excludeCustomerTagIds": [], "botsCount": 0, "categoryName": "Category Name", "templateContents": [] } ], "totalRunning": 10 }, "path": "/v1/tasks?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb", "method": "GET", "message": "success", "statusCode": 200 } ``` #### **Field Descriptions** | Field | Type | Description | | ----------------------------------- | -------- | ------------------------------------------------------------------------- | | `data` | `object` | The main response object containing the list of tasks. | | `data.data` | `array` | An array of task objects returned by the API. | | `data.data[].id` | `string` | The unique ID of the task. | | `data.data[].type` | `string` | The type of the task (e.g., "USERS"). | | `data.data[].title` | `string` | The title of the task. | | `data.data[].status` | `string` | The current status of the task (e.g., "RUNNING"). | | `data.data[].categoryId` | `string` | The ID of the category to which the task belongs. | | `data.data[].templateId` | `string` | The ID of the template associated with the task. | | `data.data[].posts` | `array` | An array of post IDs associated with the task (initially empty). | | `data.data[].images` | `array` | An array of images associated with the task (initially empty). | | `data.data[].keywords` | `array` | An array of keywords associated with the task (initially empty). | | `data.data[].keywordAddTagIds` | `array` | An array of tag IDs to add to keywords (initially empty). | | `data.data[].keywordAddGroupIds` | `array` | An array of group IDs to add to keywords (initially empty). | | `data.data[].botIds` | `array` | An array of bot IDs associated with the task. | | `data.data[].customerGroupIds` | `array` | An array of customer group IDs associated with the task. | | `data.data[].includeCustomerTagIds` | `array` | An array of customer tag IDs to include in the task. | | `data.data[].excludeCustomerTagIds` | `array` | An array of customer tag IDs to exclude from the task. | | `data.data[].botsCount` | `number` | The count of bots associated with the task. | | `data.data[].categoryName` | `string` | The name of the category to which the task belongs. | | `data.data[].templateContents` | `array` | An array of contents associated with the task template (initially empty). | | `totalRunning` | `number` | The total number of running tasks returned by the API. | | `path` | `string` | The endpoint path used for the request. | | `method` | `string` | The HTTP method used for the request (e.g., "GET"). | | `message` | `string` | A success message indicating that the task retrieval was successful. | | `statusCode` | `number` | The HTTP status code of the response (200 indicates success). | #### **Error Responses** | Status Code | Description | Example Response | | ---------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | 400 Bad Request | If the request is malformed or required parameters are missing. | `{ "statusCode": 400, "message": "Validation failed", "error": "Bad Request" }` | | 401 Unauthorized | If the user is not authenticated or does not have the necessary permissions. | `{ "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" }` | #### **Example Usage** Here is an example of how to call the endpoint using `curl`: ``` curl -X GET "https://api.shillbot.xyz/v1/tasks?appId=yourAppId&limit=10&offset=0" \ -H Authorization: Bearer or x-api-key: \ -H "Content-Type: application/json" ``` #### **Notes** * Ensure that the `appId` is valid and the user has the necessary permissions for the application. * You can modify the `limit` and `offset` parameters to paginate through the list of tasks. ## Get List of Spam #### **GET** `/spams` **Description** This endpoint retrieves a paginated list of spam records. Users can filter spam based on various criteria, including status, bot IDs, task IDs, and date ranges. #### #### **Request Headers** * `Authorization: Bearer ` or `x-api-key: ` * `Content-Type`: application/json #### **Query Parameters** #### **Query Parameters** | Name | Type | Required | Description | | ----------- | --------- | -------- | ------------------------------------------------------------------------------------------------ | | `appId` | string | Yes | The ID of the application associated with the spam records. | | `limit` | number | No | The maximum number of spam records to return (default is 10). | | `offset` | number | No | The number of spam records to skip before starting to collect the result set (default is 0). | | `status` | string | No | The status of the spam records to filter (must be one of the defined `SPAM_STATUS` enum values). | | `taskIds` | string\[] | No | An array of task IDs to filter spam records associated with specific tasks. | | `botIds` | string\[] | No | An array of bot IDs to filter spam records associated with specific bots. | | `groupIds` | string\[] | No | An array of group IDs to filter spam records associated with specific groups. | | `startDate` | Date | No | The start date for filtering spam records. | | `endDate` | Date | No | The end date for filtering spam records. | #### **Response** On successful retrieval, the response will return a JSON object structured as follows: **Success Response** ``` { "data": { "data": [ { "id": "75303efc-8424-4483-8abb-ffb089978574", "error": null, "status": "DONE", "postState": "CAN_POST", "postView": 0, "likeCount": 0, "replyCount": 0, "retweetCount": 0, "appId": "fd8e0a24-f5de-4736-834d-9388f00e48eb", "botId": "4363bbb1-15ee-4097-9185-4898c9c87c11", "jobId": "7710", "taskId": "b465d542-46a7-4162-aadc-374e2f00fe28", "images": [], "content": "this is content", "tweetId": "1841724411851710604", "tweetUrl": "https://x.com/AIIMSRDA/status/1841724411851710604", "customerId": "7f332bee-1587-48ab-8782-ddd8600e5751", "postTweetId": "1842356034062434384", "errorMessage": null, "paymentItemId": null, "interactionJobId": "7712", "increateViewJobId": null, "isInteraction": true, "postTime": "2024-10-05T00:07:11.745Z", "createdAt": "2024-10-05T00:02:11.997Z", "updatedAt": "2024-10-05T00:09:03.288Z", "interactionAt": "2024-10-05T00:09:03.287Z", "increateViewAt": null, "customer": { "id": "7f332bee-1587-48ab-8782-ddd8600e5751", "name": "AIIMSRDA", "appId": "fd8e0a24-f5de-4736-834d-9388f00e48eb", "isDeleted": false, "isHide": true, "taskCount": 1, "interactionCount": 0, "createdAt": "2024-10-05T00:02:11.940Z", "updatedAt": "2024-10-05T00:08:05.294Z", "lastPostAt": null, "customerGroups": [] }, "interactions": [], "task": { "id": "b465d542-46a7-4162-aadc-374e2f00fe28", "title": "this is task name" }, "bot": { "id": "4363bbb1-15ee-4097-9185-4898c9c87c11", "username": "this is bot name" } } // Additional spam records... ], "total": 14, "stat": { "views": 0, "likes": 0, "replies": 0, "reposts": 0 } }, "path": "/v1/spams?limit=30&appId=fd8e0a24-f5de-4736-834d-9388f00e48eb&offset=0&endDate=2024-10-05T23:59:59.999Z&startDate=2024-10-05T00:00:00.000Z", "method": "GET", "message": "success", "statusCode": 200 } ``` #### **Field Descriptions** | Field | Type | Description | | ------------------------------ | ------------------ | --------------------------------------------------------------------------------------------- | | `data` | `object` | The main response object containing the list of spam records. | | `data.data` | `array` | An array of spam objects returned by the API. | | `data.data[].id` | `string` | The unique ID of the spam record. | | `data.data[].error` | `string` or `null` | Error message, if applicable (e.g., "TWEET\_NOT\_FOUND"). | | `data.data[].status` | `string` | The current status of the spam record (e.g., "DONE", "ERROR", "WAITING"). | | `data.data[].postState` | `string` | The state of the post (e.g., "CAN\_POST"). | | `data.data[].postView` | `number` | The view count for the post. | | `data.data[].likeCount` | `number` | The count of likes associated with the spam record. | | `data.data[].replyCount` | `number` | The count of replies associated with the spam record. | | `data.data[].retweetCount` | `number` | The count of retweets associated with the spam record. | | `data.data[].appId` | `string` | The application ID associated with the spam record. | | `data.data[].botId` | `string` or `null` | The ID of the bot associated with the spam record, if applicable. | | `data.data[].jobId` | `string` | The job ID associated with the spam record. | | `data.data[].taskId` | `string` | The task ID associated with the spam record. | | `data.data[].images` | `array` | An array of image URLs associated with the spam record (if any). | | `data.data[].content` | `string` or `null` | The content of the spam record (if applicable). | | `data.data[].tweetId` | `string` or `null` | The ID of the tweet associated with the spam record (if applicable). | | `data.data[].tweetUrl` | `string` or `null` | The URL of the tweet associated with the spam record (if applicable). | | `data.data[].customerId` | `string` | The ID of the customer associated with the spam record. | | `data.data[].postTweetId` | `string` or `null` | The ID of the post associated with the spam record (if applicable). | | `data.data[].errorMessage` | `string` or `null` | Error message associated with the spam record, if applicable. | | `data.data[].paymentItemId` | `string` or `null` | Payment item ID associated with the spam record, if applicable. | | `data.data[].interactionJobId` | `string` or `null` | Job ID for interactions associated with the spam record, if applicable. | | `data.data[].isInteraction` | `boolean` | Indicates if this record is part of an interaction. | | `data.data[].postTime` | `string` | The timestamp when the spam was posted. | | `data.data[].createdAt` | `string` | The timestamp when the spam record was created. | | `data.data[].updatedAt` | `string` | The timestamp when the spam record was last updated. | | `data.data[].interactionAt` | `string` or `null` | The timestamp of the last interaction, if applicable. | | `data.data[].customer` | `object` | An object containing details of the associated customer. | | `data.data[].task` | `object` | An object containing details of the associated task. | | `data.data[].bot` | `object` | An object containing details of the associated bot (if applicable). | | `data.total` | `number` | The total number of spam records returned by the API. | | `data.stat` | `object` | An object containing statistics related to the spam records (views, likes, replies, reposts). | | `path` | `string` | The endpoint path used for the request. | | `method` | `string` | The HTTP method used for the request (e.g., "GET"). | | `message` | `string` | A success message indicating that the spam retrieval was successful. | | `statusCode` | `number` | The HTTP status code of the response (200 indicates success). | #### **Error Responses** | Status Code | Description | Example Response | | ---------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | 400 Bad Request | If the request is malformed or required parameters are missing. | `{ "statusCode": 400, "message": "Validation failed", "error": "Bad Request" }` | | 401 Unauthorized | If the user is not authenticated or does not have the necessary permissions. | `{ "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" }` | #### **Example Usage** Here is an example of how to call the endpoint using `curl`: ``` curl -X GET "/v1/spams?appId=yourAppId&limit=30&offset=0&startDate=2024-10-05T00:00:00.000Z&endDate=2024-10-05T23:59:59.999Z" \ -H Authorization: Bearer or x-api-key: \ -H "Content-Type: application/json" ``` #### **Notes** * Ensure that the `appId` is valid and the user has the necessary permissions for the application. * You can modify the `limit`, `offset`, `startDate`, and `endDate` parameters to paginate through the list of spam records. #### Create Group API **Endpoint:**\ `POST /v1/customers/groups` **Description:**\ This endpoint allows you to create a new customer group for organizing customers. **Request:** * **URL:** `/v1/customers/groups` * **Method:** `POST` * **Headers:** * `Content-Type: application/json` * `Authorization: Bearer ` or `x-api-key: ` **Body Parameters:** | Parameter | Type | Required | Description | | --------- | -------- | -------- | --------------------------------------- | | `name` | `string` | Yes | The name of the group you are creating. | **Query Parameters:** | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------ | | `appId` | string | Yes | The application ID linked to the group creation. | **Sample Request:** **Payload:** ``` { "name": "test shillbot" } ``` Query Parameters: ``` ?appId=db7c5f31-3182-4f81-a196-f656e61c180f ``` #### Responses: ``` { "data": { "name": "test shillbot", "id": "25c93965-091f-4dff-abf0-e67877f663a9" }, "path": "/v1/customers/groups?appId=db7c5f31-3182-4f81-a196-f656e61c180f", "method": "POST", "message": "success", "statusCode": 200 } ``` Field description: #### **Field Descriptions:** | Field | Type | Description | | ------------ | ------- | ------------------------------------------------------------------------------------------------------------ | | `data` | object | Contains information about the newly created group. | | `data.name` | string | The name of the created group. In this example, `"test shillbot"`. | | `data.id` | string | The unique identifier assigned to the group. In this example, `"25c93965-091f-4dff-abf0-e67877f663a9"`. | | `path` | string | The API endpoint path that was accessed, including the query parameters. Shows the full request path. | | `method` | string | The HTTP method used for the request. In this case, it is `"POST"`. | | `message` | string | A brief message indicating the result of the API call. `"success"` means the group was created successfully. | | `statusCode` | integer | The HTTP status code of the response. A value of `200` indicates that the request was successful. | ## Get Customer Groups API #### **Endpoint:** `GET /v1/customers/groups` #### **Description:** This endpoint retrieves a list of customer groups based on the provided query parameters, such as date ranges, application ID, and pagination details. #### **Authentication:** This endpoint requires bearer token authentication. The user must have appropriate permissions to access the customer groups. #### **Request:** * **URL:** `/v1/customers/groups` * **Method:** `GET` * **Headers:** * `Authorization: Bearer ` or `x-api-key: ` * `Content-Type: application/json` #### **Query Parameters:** | Parameter | Type | Required | Description | | ----------- | ------- | -------- | -------------------------------------------------------------------------------------- | | `limit` | integer | Yes | The maximum number of records to retrieve. Example: `1000`. | | `appId` | string | Yes | The application ID to filter the customer groups by. | | `offset` | integer | Yes | The offset for pagination, specifying where to start retrieving records. Example: `0`. | | `startDate` | string | Yes | The start of the date range in ISO format. Example: `2024-10-07T00:00:00.000Z`. | | `endDate` | string | Yes | The end of the date range in ISO format. Example: `2024-10-07T23:59:59.999Z`. | Sample Request: ``` GET https://api.shillbot.xyz/v1/customers/groups?limit=1000&appId=db7c5f31-3182-4f81-a196-f656e61c180f&offset=0&startDate=2024-10-07T00:00:00.000Z&endDate=2024-10-07T23:59:59.999Z ``` #### **Response:** **Success Response:** ``` { "data": { "total": 1, "data": [ { "name": "test shillbot", "id": "25c93965-091f-4dff-abf0-e67877f663a9" } ] }, "path": "/v1/customers/groups?limit=1000&appId=db7c5f31-3182-4f81-a196-f656e61c180f&offset=0&endDate=2024-10-07T23:59:59.999Z&startDate=2024-10-07T00:00:00.000Z", "method": "GET", "message": "success", "statusCode": 200 } ``` #### **Field Descriptions:** | Field | Type | Description | | ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------- | | **data** | object | Contains the response details for customer groups. | | **data.total** | integer | The total number of customer groups that match the query. | | **data.data** | array | An array of customer group objects that match the query. | | **data.data.name** | string | The name of the customer group. In this case, `"test shillbot"`. | | **data.data.id** | string | The unique identifier for the customer group. | | **path** | string | The request path that was used, including the query parameters. | | **method** | string | The HTTP method used for the request, in this case, `"GET"`. | | **message** | string | A brief message about the result of the API call. `"success"` indicates that the request was processed successfully. | | **statusCode** | integer | The HTTP status code returned by the server. A value of `200` indicates that the request was successful. | #### **Notes:** * Make sure that the **appId** is valid, and that the user has the necessary permissions to retrieve customer groups. * The **limit** and **offset** parameters can be used to paginate through the customer groups. * The **startDate** and **endDate** parameters filter the results within a specific date range. ## Get List Tags #### **Endpoint:** `GET /v1/customers/tags` #### **Description:** This endpoint retrieves a list of customer tags based on the provided query parameters, such as date ranges, application ID, and pagination details. If no tags are found, the `data` array will be empty. #### **Authentication:** This endpoint requires bearer token authentication. Users must have appropriate permissions to access the customer tags. #### **Request:** * **URL:** `/v1/customers/tags` * **Method:** `GET` * **Headers:** * `Authorization: Bearer ` or `x-api-key: ` * `Content-Type: application/json` #### **Query Parameters:** | Parameter | Type | Required | Description | | ----------- | ------- | -------- | -------------------------------------------------------------------------------------- | | `limit` | integer | Yes | The maximum number of records to retrieve. Example: `1000`. | | `appId` | string | Yes | The application ID to filter the customer tags by. | | `offset` | integer | Yes | The offset for pagination, specifying where to start retrieving records. Example: `0`. | | `startDate` | string | Yes | The start of the date range in ISO format. Example: `2024-10-07T00:00:00.000Z`. | | `endDate` | string | Yes | The end of the date range in ISO format. Example: `2024-10-07T23:59:59.999Z`. | Sample Request: ``` GET /v1/customers/tags?limit=1000&appId=db7c5f31-3182-4f81-a196-f656e61c180f&offset=0&startDate=2024-10-07T00:00:00.000Z&endDate=2024-10-07T23:59:59.999Z ``` #### **Response:** **Success Response:** ``` { "data": { "total": 0, "data": [] }, "path": "/v1/customers/tags?limit=1000&appId=db7c5f31-3182-4f81-a196-f656e61c180f&offset=0&endDate=2024-10-07T23:59:59.999Z&startDate=2024-10-07T00:00:00.000Z", "method": "GET", "message": "success", "statusCode": 200 } ``` #### **Field Descriptions:** | Field | Type | Description | | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | **data** | object | Contains the response details for customer tags. | | **data.total** | integer | The total number of customer tags that match the query. In this case, `0` indicates no tags were found. | | **data.data** | array | An array of customer tag objects that match the query. In this case, the array is empty as no tags were found. | | **path** | string | The request path that was used, including the query parameters. | | **method** | string | The HTTP method used for the request, in this case, `"GET"`. | | **message** | string | A brief message about the result of the API call. `"success"` indicates that the request was processed successfully. | | **statusCode** | integer | The HTTP status code returned by the server. A value of `200` indicates that the request was successful. | ## Import User **Endpoint:** `POST /v1/customers/batch` **Description:**\ This endpoint allows you to batch create or import customers into the system. You can use various filtering criteria or provide specific names, tags, and groups to associate customers with. The batch creation allows up to 1000 customer names in a single request. **Authentication:** This endpoint requires either: * `Authorization: Bearer ` * `x-api-key: ` **Request:** * **URL:**\ `https://api.shillbot.xyz/v1/customers/batch?appId=yourAppId` * **Method:**\ `POST` * **Headers:** * `Authorization: Bearer ` or `x-api-key: ` * `Content-Type: application/json` * **Query Parameters:** * `appId` (string, required): The ID of the application that will be associated with the customers being created. **Request Body:** #### Payload Fields Description | **Field** | **Type** | **Description** | | ---------- | --------------------------- | ---------------------------------------------------------------------------------------- | | `type` | enum (required) | The type of batch operation. Must be one of the values defined in `CUSTOMER_BATCH_TYPE`. | | `names` | array of strings | An array of customer names to import. Limited to 1000 names per request. | | `tagIds` | array of strings | An array of tag IDs to associate with the customers. Limited to 100 IDs. | | `groupIds` | array of strings | An array of group IDs to associate with the customers. Limited to 100 IDs. | | `filter` | object (optional) | Filtering criteria for importing customers. | | `ids` | array of strings (optional) | Array of customer IDs to be included. | The request body must be a JSON object that follows the structure defined by the ``` { "type": "IMPORT_CUSTOMERS", "names": [ "username" ], "tagIds": ["8d598761-1276-44da-88bb-6629116feaa1"], "groupIds": ["068ece90-f1db-4402-84c0-e5a5fa0be585"] } ``` **Response:** On a successful request, the response will contain the path of the request, the HTTP method used, and a success message with status code 200. ``` { "path": "/v1/customers/batch?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb", "method": "POST", "message": "success", "statusCode": 200 } ``` #### Response Fields Description | **Field** | **Type** | **Description** | | ------------ | -------- | -------------------------------------------------------------------------------------------------- | | `path` | string | The API path used for the request. | | `method` | string | The HTTP method used in the request. In this case, it will always be `"POST"`. | | `message` | string | Describes the result of the request. On success, this field will return `"success"`. | | `statusCode` | integer | The HTTP status code for the response. A value of `200` indicates that the request was successful. | **Example Usage:** Here’s an example of how to call the endpoint using `curl`: ``` curl -X POST "https://api.shillbot.xyz/v1/customers/batch?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb" \ -H "Authorization: Bearer " or "x-api-key: " \ -H "Content-Type: application/json" \ -d '{ "type": "IMPORT_CUSTOMERS", "names": ["username"], "tagIds": ["8d598761-1276-44da-88bb-6629116feaa1"], "groupIds": ["068ece90-f1db-4402-84c0-e5a5fa0be585"] }' ``` ## Notifications API #### Endpoint `GET /v1/bots/notification` #### Description Retrieve a list of notifications for the user based on specified filters, including type, user details, and notification status. #### Authentication * **Bearer Token** is required. #### Parameters | Parameter | Type | Description | | ----------- | ------- | --------------------------------------------------------------------------- | | `limit` | Integer | The number of notifications to return. Default: `30`. | | `appId` | String | Application identifier. Required. | | `offset` | Integer | The starting position for the list of notifications. Default: `0`. | | `startDate` | Date | Start date in ISO 8601 format (e.g., `2024-11-02T00:00:00.000Z`). Required. | | `endDate` | Date | End date in ISO 8601 format (e.g., `2024-11-02T23:59:59.999Z`). Required. | #### Response * **Status**: 200 OK * **Response Body**: * **data.total**: Integer - Total number of notifications. * **data.unRead**: Integer - Count of unread notifications. * **data.data**: Array - List of notification objects, each containing: | Field | Type | Description | | ------------------ | ------- | -------------------------------------------------------- | | `type` | String | Notification type (e.g., `users_liked_your_tweet`). | | `fromUser` | String | Display name of the user who triggered the notification. | | `fromUserId` | String | ID of the user who triggered the notification. | | `fromUserName` | String | Username of the user who triggered the notification. | | `fromUserAvatar` | String | URL of the user's profile image. | | `tweetId` | String | ID of the associated tweet, if applicable. | | `replyTweetId` | String | ID of the reply tweet, if applicable. | | `mentionTweetId` | String | ID of the mention tweet, if applicable. | | `notificationText` | String | The text of the notification message. | | `read` | Boolean | Read status of the notification. | | `isBot` | Boolean | Indicates if the notification is bot-generated. | | `notificationAt` | Date | Timestamp when the notification was created. | | `id` | String | Unique identifier for the notification. | **Example Request** ``` GET https://api.shillbot.xyz/v1/bots/notification?limit=30&appId=fd8e0a24-f5de-4736-834d-9388f00e48eb&offset=0&endDate=2024-11-02T23:59:59.999Z&startDate=2024-11-02T00:00:00.000Z Authorization: Bearer {token} ``` **Example Response** ``` { "data": { "total": 40, "data": [ { "type": "users_liked_your_tweet", "fromUser": "Global Crypto Federation I GCF", "fromUserId": "977614921", "fromUserName": "Glbcryptofed", ... } ], "unRead": 12 }, "message": "success", "statusCode": 200 } ``` ## Example