GET — Chats / Leads Listing

Retrieve a paginated list of chats or leads and their metadata for a specific bot. Use the type parameter to switch between leads and non-lead chats.

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 [e-mail] 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

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

{
  "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": "[e-mail]",
            "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" %}

{
  "success": true,
  "message": "ok",
  "code": 200,
  "data": [...]
}

Request successful. Records returned in data array. {% endtab %}

{% tab title="400 Bad Request" %}

{
  "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" %}

{
  "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 [e-mail]