For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 support@botpenguin.com 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


Response

Success — 200 OK

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

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

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

Missing or invalid query parameters. Check botId, customerId, page, and type. {% endtab %}

{% tab title="401 Unauthorized" %}

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

Last updated

Was this helpful?