> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/api-documentation/contacts-and-chats-apis/get-chats-leads-listing.md). # GET — Chats / Leads Listing ### Overview | Property | Details | | ----------------- | -------------------------------------------------- | | **Method** | `GET` | | **Endpoint** | `https://api.v7.botpenguin.com/inbox/direct/chats` | | **Base URL** | `https://api.v7.botpenguin.com` | | **API Version** | v7 | | **Auth Required** | Yes — `x-bot-token` | | **Content-Type** | `application/json` | *** ### Authentication | Header | Required | Value | | ------------- | -------- | ------------------------- | | `x-bot-token` | ✅ Yes | Your BotPenguin API Token | > 🔑 **Where to get your token:** Contact to obtain your `x-bot-token`. *** ### Request #### Headers | Header | Required | Value | | -------------- | -------- | ------------------------- | | `x-bot-token` | ✅ Yes | Your BotPenguin API Token | | `Content-Type` | ✅ Yes | `application/json` | *** #### Query Parameters | Parameter | Type | Required | Description | | ------------ | -------- | -------- | ---------------------------------------------------------------------------------------------------- | | `botId` | `string` | ✅ Yes | Unique ID of the bot. | | `customerId` | `string` | ✅ Yes | Unique ID of the customer account. | | `page` | `string` | ✅ Yes | Page number for paginated results. Starts at `1`. | | `type` | `string` | ✅ Yes | Type of records to retrieve. Values: `lead` to fetch leads only, `non-lead` to fetch non-lead chats. | *** #### Example Request ```bash curl 'https://api.v7.botpenguin.com/inbox/direct/chats?botId=638d99eeee9e558f1247ae03&customerId=5fed38e56fb193dcc6c933f5&page=1&type=lead' \ -H 'x-bot-token: YOUR_API_TOKEN' \ -H 'Content-Type: application/json' ``` *** ### Response #### Success — `200 OK` ```json { "success": true, "message": "ok", "code": 200, "data": [ { "_id": "63d9ffa77a8d152facbe2f2f", "uuid": "7e88d192-9b20-4035-9b68-d4ac3d58a34f", "isOnline": false, "status": "INPROGRESS", "websiteVisits": 1, "_agentAssigned": "631aa793bcfa100487d13d0d", "lastMessage": { "at": "2023-02-01T06:00:20.000Z", "by": "bot", "text": "Welcome to BotPenguin. I am here to help you." }, "lastSeenAt": "2023-02-01T06:00:21.000Z", "profile": { "notes": [ { "_id": "63db5c4abcbc3be2e95b20ae", "title": "Sample title", "description": "Sample description" } ], "userDetails": { "name": "Sample name", "picture": "https://example.com/avatar.jpg", "contact": { "email": "sample@email.com", "phone": { "number": "9876543210", "prefix": "91" } }, "city": "Sample city", "country": "Sample country", "gender": "MALE", "tags": ["Sample tag"], "attributes": [ { "key": "ID", "value": "BP001" } ] } }, "createdAt": "2023-02-01T05:59:03.533Z", "updatedAt": "2023-02-02T06:46:34.119Z" } ] } ``` **Response Fields** **Root Level** | Field | Type | Description | | --------- | --------- | ----------------------------------------- | | `success` | `boolean` | `true` if the request was successful. | | `message` | `string` | Status message. Value: `"ok"` on success. | | `code` | `number` | HTTP status code echo. `200` on success. | | `data` | `array` | Paginated list of chat or lead records. | *** **`data[]` — Chat / Lead Object** | Field | Type | Description | | ------------------ | ------------------- | ---------------------------------------------------------------------------------------------- | | `_id` | `string` | Unique identifier of the chat record. | | `uuid` | `string` | Session UUID of the chat user. | | `isOnline` | `boolean` | `true` if the user is currently active. | | `status` | `string` | Conversation status. Values: `OPEN`, `INPROGRESS`, `REVIEW`, `ONHOLD`, `DEPENDANCY`, `CLOSED`. | | `websiteVisits` | `number` | Number of times this user has visited the website. | | `_agentAssigned` | `string` | ID of the agent assigned to this chat. | | `lastMessage` | `object` | Details of the most recent message. | | `lastMessage.at` | `string (ISO 8601)` | Timestamp of the last message. | | `lastMessage.by` | `string` | Sender of the last message. Values: `bot`, `user`, `agent`. | | `lastMessage.text` | `string` | Content of the last message. | | `lastSeenAt` | `string (ISO 8601)` | Timestamp when the user was last active. | | `profile` | `object` | User profile data. See `profile` object below. | | `createdAt` | `string (ISO 8601)` | Timestamp when the chat record was created. | | `updatedAt` | `string (ISO 8601)` | Timestamp when the chat record was last updated. | *** **`profile` Object** | Field | Type | Description | | ---------------------------------- | -------- | ------------------------------------------------------------------- | | `userDetails.name` | `string` | Full name of the user. | | `userDetails.picture` | `string` | URL of the user's profile picture. | | `userDetails.contact.email` | `string` | User's email address. | | `userDetails.contact.phone.number` | `string` | Phone number without country code. | | `userDetails.contact.phone.prefix` | `string` | Country dial code without `+`. Example: `91`. | | `userDetails.city` | `string` | User's city. | | `userDetails.country` | `string` | User's country. | | `userDetails.gender` | `string` | User's gender. Example: `MALE`, `FEMALE`. | | `userDetails.tags` | `array` | Labels assigned to this user. | | `userDetails.attributes` | `array` | Custom key-value data. Each entry contains `key` and `value`. | | `notes` | `array` | Agent notes. Each entry contains `_id`, `title`, and `description`. | *** ### HTTP Status Codes {% tabs %} {% tab title="200 OK" %} ```json { "success": true, "message": "ok", "code": 200, "data": [...] } ``` Request successful. Records returned in `data` array. {% endtab %} {% tab title="400 Bad Request" %} ```json { "success": false, "message": "Bad request / invalid parameters", "code": 400 } ``` Missing or invalid query parameters. Check `botId`, `customerId`, `page`, and `type`. {% endtab %} {% tab title="401 Unauthorized" %} ```json { "success": false, "message": "Unauthorized request", "code": 401 } ``` `x-bot-token` is missing, invalid, or expired. {% endtab %} {% endtabs %} *** ### Rate Limits This endpoint is limited to **100 requests per minute** per token, across all plans. Exceeding this returns `429 Too Many Requests`. Use the `Retry-After` response header (in seconds) to schedule your retry. *** *For questions or issues, contact* [*support@botpenguin.com*](mailto:support@botpenguin.com)