POST — Get User Inbox

Retrieve a paginated list of contacts and their conversation metadata from the BotPenguin inbox. Supports filtering by platform, agent, status, tags, segments, date ranges, and more.

Overview

Property	Details
Method	POST
Endpoint	https://api.v7.botpenguin.com/inbox/users
Base URL	https://api.v7.botpenguin.com
API Version	v7
Auth Required	Yes — Bearer Token
Content-Type	application/json

---

Authentication

This endpoint uses a Bearer Token passed in the Authorization header, along with an authtype header to specify the token type.

Header	Required	Value
Authorization	✅ Yes	Bearer YOUR_API_TOKEN
authtype	✅ Yes	Key

🔑 Where to get your API Token: Contact [e-mail] to obtain your token.

---

Request

Headers

Header	Required	Value
Authorization	✅ Yes	Bearer YOUR_API_TOKEN
authtype	✅ Yes	Key
Content-Type	✅ Yes	application/json

---

Request Body

All fields are required. Pass empty values ("", [], false) for filters you do not wish to apply.

{
  "searchText": "",
  "tags": [],
  "status": [],
  "isOnline": false,
  "_botWebsite": [],
  "_botWhatsapp": [],
  "_botTelegram": [],
  "_botFacebook": [],
  "_agentAssigned": [],
  "segments": [],
  "applicableFilters": ["userInteracted"],
  "lastSeenAt": {
    "startAt": "",
    "endsAt": ""
  },
  "createdAt": {
    "startAt": "",
    "endsAt": ""
  },
  "userInteracted": true,
  "lastMessageBy": [],
  "isLiveChatActive": false,
  "hasOrdered": {
    "status": false,
    "lastAt": ""
  },
  "page": 1,
  "isExport": "none",
  "isContact": true
}

Body Fields

Field	Type	Description
searchText	string	Free-text search to filter contacts by name, email, or phone. Pass "" to return all.
tags	array	Filter contacts by one or more tag labels. Pass [] for no tag filter.
status	array	Filter by conversation status. Values: OPEN, INPROGRESS, REVIEW, ONHOLD, DEPENDANCY, CLOSED. Pass [] for all statuses.
isOnline	boolean	true to return only currently online users. false for all.
_botWebsite	array	Filter contacts who interacted via a specific Website bot. Pass bot IDs. Pass [] for all.
_botWhatsapp	array	Filter contacts who interacted via a specific WhatsApp bot. Pass bot IDs. Pass [] for all.
_botTelegram	array	Filter contacts who interacted via a specific Telegram bot. Pass bot IDs. Pass [] for all.
_botFacebook	array	Filter contacts who interacted via a specific Facebook bot. Pass bot IDs. Pass [] for all.
_agentAssigned	array	Filter contacts assigned to specific agents. Pass agent IDs. Pass [] for all.
segments	array	Filter contacts belonging to specific segments. Pass segment IDs. Pass [] for all.
applicableFilters	array	Active filter keys to apply. Example: ["userInteracted"]. Pass [] to disable.
lastSeenAt	object	Date range filter for when the user was last seen.
lastSeenAt.startAt	string (ISO 8601)	Start of the last seen date range. Pass "" to ignore.
lastSeenAt.endsAt	string (ISO 8601)	End of the last seen date range. Pass "" to ignore.
createdAt	object	Date range filter for when the contact was created.
createdAt.startAt	string (ISO 8601)	Start of the creation date range. Pass "" to ignore.
createdAt.endsAt	string (ISO 8601)	End of the creation date range. Pass "" to ignore.
userInteracted	boolean	true to return only contacts who have interacted with the bot.
lastMessageBy	array	Filter by who sent the last message. Values: bot, user, agent. Pass [] for all.
isLiveChatActive	boolean	true to return only contacts with an active live chat session.
hasOrdered	object	Filter contacts based on order history.
hasOrdered.status	boolean	true to return only contacts who have placed an order.
hasOrdered.lastAt	string (ISO 8601)	Filter by last order date. Pass "" to ignore.
page	number	Page number for paginated results. Starts at 1.
isExport	string	Export mode flag. Pass "none" for standard API retrieval.
isContact	boolean	true to return only confirmed contacts.

---

Example Request

curl 'https://api.v7.botpenguin.com/inbox/users' \
  -X 'POST' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'authtype: Key' \
  -H 'Content-Type: application/json' \
  -d '{
    "searchText": "",
    "tags": [],
    "status": [],
    "isOnline": false,
    "_botWebsite": [],
    "_botWhatsapp": [],
    "_botTelegram": [],
    "_botFacebook": [],
    "_agentAssigned": [],
    "segments": [],
    "applicableFilters": ["userInteracted"],
    "lastSeenAt": { "startAt": "", "endsAt": "" },
    "createdAt": { "startAt": "", "endsAt": "" },
    "userInteracted": true,
    "lastMessageBy": [],
    "isLiveChatActive": false,
    "hasOrdered": { "status": false, "lastAt": "" },
    "page": 1,
    "isExport": "none",
    "isContact": true
  }'

---

Response

Success — 200 OK

{
  "success": true,
  "message": "",
  "code": 200,
  "data": [
    {
      "_id": "6a2bbfbe1a0899b1ad04bf58",
      "_agency": "5fed22a15383a9a5135e925d",
      "_customer": "5fed38e56fb193dcc6c933f5",
      "uuid": "e15bf245-44e3-4da2-89c2-23c8fb487214",
      "platform": ["WEBSITE"],
      "secondaryPlatform": ["website"],
      "_aiAgent": "6891d66c35b30cd878987865",
      "isSubscriber": true,
      "websiteVisits": 0,
      "isOnline": true,
      "userInteracted": true,
      "profile": {
        "userDetails": {
          "name": "",
          "contact": {
            "email": "",
            "phone": { "number": "", "prefix": "" }
          },
          "city": "",
          "country": "",
          "gender": "",
          "tags": [],
          "attributes": []
        },
        "notes": [],
        "marketing": { "urlsVisited": [] }
      },
      "status": "ONHOLD",
      "lastSeenAt": "2026-06-12T08:13:50.000Z",
      "lastMessage": {
        "at": "2026-06-12T08:13:52.369Z",
        "text": "I am here to help you.",
        "by": "bot"
      },
      "isContact": true,
      "isImported": false,
      "isMigrated": false,
      "segments": [],
      "isLiveChatActive": false,
      "isPaid": true,
      "hasOrdered": { "status": false },
      "unreadMessages": 0,
      "integrations": { "zoho": { "isTemplateSent": false } },
      "chatBotType": "AGENTIC",
      "emailNotificationSent": false,
      "unreadMessage": [
        { "userId": "5fed38e56fb193dcc6c933f5", "count": 0 }
      ],
      "createdAt": "2026-06-12T08:13:50.362Z",
      "updatedAt": "2026-06-12T10:00:02.910Z",
      "__v": 0
    }
  ]
}

Response Fields

Root Level

Field	Type	Description
success	boolean	true if the request was successful.
message	string	Status message. Empty string on success.
code	number	HTTP status code echo. 200 on success.
data	array	Paginated list of contact records matching the applied filters.

---

data[] — Contact Object

Field	Type	Description
_id	string	Unique identifier of the contact record.
_agency	string	ID of the agency account this contact belongs to.
_customer	string	ID of the customer (sub-account) this contact belongs to.
uuid	string	Browser-generated unique session identifier for the contact.
platform	array	Primary platform(s) the contact interacted through. Values: WEBSITE, WHATSAPP, TELEGRAM, FACEBOOK, INSTAGRAM.
secondaryPlatform	array	Secondary platform associations.
_botWebsite	string	(Conditional) ID of the Website bot, if platform is WEBSITE.
_botWhatsapp	string	(Conditional) ID of the WhatsApp bot, if platform is WHATSAPP.
_botTelegram	string	(Conditional) ID of the Telegram bot, if platform is TELEGRAM.
_botFacebook	string	(Conditional) ID of the Facebook bot, if platform is FACEBOOK.
_botAutomation	string	(Conditional) ID of the automation bot, if platform is INSTAGRAM.
_aiAgent	string	(Conditional) ID of the AI Agent, present when chatBotType is AGENTIC.
_user	string	Internal platform-specific user record ID.
_userWebsite	string	(Conditional) Website-specific user record ID.
_userWhatsapp	string	(Conditional) WhatsApp-specific user record ID.
_userTelegram	string	(Conditional) Telegram-specific user record ID.
_userFacebook	string	(Conditional) Facebook-specific user record ID.
_userAutomation	string	(Conditional) Automation-specific user record ID.
_agentAssigned	string	(Conditional) ID of the agent assigned to this contact. Present only when an agent is assigned.
isSubscriber	boolean	true if the contact has subscribed to communications.
websiteVisits	number	Number of times this contact has visited the website.
isOnline	boolean	true if the contact is currently active.
userInteracted	boolean	true if the contact has sent at least one message.
status	string	Current conversation status. Values: OPEN, INPROGRESS, REVIEW, ONHOLD, DEPENDANCY, CLOSED.
isContact	boolean	true if this record is a confirmed contact.
isImported	boolean	true if this contact was imported externally.
isMigrated	boolean	true if this contact was migrated from a legacy system.
isUserBlocked	boolean	true if this contact has been blocked.
isLiveChatActive	boolean	true if a live chat session is currently active for this contact.
isPaid	boolean	true if this contact's conversation is counted as a paid interaction.
emailNotificationSent	boolean	(AGENTIC bots only) true if an email notification was sent for this conversation.
chatBotType	string	Type of bot handling this conversation. Values: FLOW_BASED, AGENTIC.
segments	array	List of segment IDs this contact belongs to. Empty if none.
lastSeenAt	string (ISO 8601)	Timestamp of when the contact was last active.
lastMessage	object	Details of the most recent message in the conversation.
lastMessage.text	string	Content of the last message.
lastMessage.at	string (ISO 8601)	Timestamp of the last message.
lastMessage.by	string	Sender of the last message. Values: bot, user, agent.
unreadMessages	number	Total count of unread messages for the default view.
unreadMessage	array	Per-agent unread message counts. Each entry contains userId and count.
hasOrdered	object	Order history summary for this contact.
hasOrdered.status	boolean	true if the contact has placed an order.
hasOrdered.lastAt	string (ISO 8601)	(Conditional) Timestamp of the most recent order. Present only if status is true.
integrations	object	Third-party integration states for this contact.
integrations.zoho.isTemplateSent	boolean	true if a Zoho template was sent for this contact.
conversationSummary	object	AI-generated conversation summary. Present for FLOW_BASED bots.
conversationSummary.summary	string	Text summary of the conversation. Empty if not yet generated.
conversationSummary.errorStatus	object	Error state of the summary generation. Contains isError, code, messageKey, fallbackMessage.
profile	object	Contact profile data. See profile object below.
createdAt	string (ISO 8601)	Timestamp when this contact record was created.
updatedAt	string (ISO 8601)	Timestamp when this contact record was last updated.
__v	number	Internal document version. Not for application use.

---

profile Object

Field	Type	Description
userDetails.name	string	Contact's display name.
userDetails.picture	string	URL of the contact's profile picture.
userDetails.contact.email	string	Contact's email address.
userDetails.contact.phone.number	string	Phone number without country prefix.
userDetails.contact.phone.prefix	string	Country dial code. Example: +91.
userDetails.whatsAppNumber	string	Full WhatsApp number with country code. Present for WhatsApp contacts.
userDetails.telegramUserName	string	Telegram username. Present for Telegram contacts.
userDetails.telegramChatId	string	Telegram chat ID. Present for Telegram contacts.
userDetails.facebookProfileId	string	Facebook profile ID. Present for Facebook contacts.
userDetails.instagramUserName	string	Instagram username. Present for Instagram contacts.
userDetails.instagramProfileId	string	Instagram profile ID. Present for Instagram contacts.
userDetails.city	string	Contact's city, detected from IP or provided by the user.
userDetails.country	string	Contact's country code. Example: IN, US.
userDetails.gender	string	Contact's gender, if provided.
userDetails.tags	array	Tags assigned to this contact.
userDetails.attributes	array	Custom key-value attributes. Each entry contains key and value.
userDetails.userProvidedName	string	(Conditional) Name provided by the user during the conversation, if different from the profile name.
notes	array	Agent notes attached to this contact. Each entry contains title, description, and _id.
marketing.urlsVisited	array	List of URLs visited by this contact during their session.
device.device	string	Device type and model. Example: Desktop(Apple Macintosh).
device.browser	string	Browser and version. Example: Chrome 148.0.0.0.
device.ip	string	Contact's IP address at time of interaction.
device.operatingSystem	string	Operating system. Example: Mac OS 10.15.7.

---

Contact Status Reference

Status	Description
OPEN	Conversation is open and active.
INPROGRESS	An agent is actively working on this conversation.
REVIEW	Conversation is pending review.
ONHOLD	Conversation is paused or on hold.
DEPENDANCY	Conversation is blocked on an external dependency.
CLOSED	Conversation has been closed.

---

HTTP Status Codes

Code	Status	Meaning
200	OK	Request succeeded. Contacts returned in data array.
400	Bad Request	Missing or invalid parameters. Check required fields.
401	Unauthorized	Bearer token is missing, invalid, or expired.
429	Too Many Requests	Rate limit exceeded. Retry after the indicated window.
500	Internal Server Error	Server-side error. Contact support if it persists.

---

Error Handling

All errors return a consistent structure:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Bearer token is invalid or has expired.",
    "statusCode": 401
  }
}

---

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.

---

Related APIs

• GET — Get All Templates — Retrieve approved WhatsApp templates for your bot.

• POST — Send WhatsApp Message — Send a message to a specific contact.

• POST — Send WhatsApp Template Message — Send a template message to a contact.

• API Authentication Guide — How to obtain and manage your API token.

---

For questions or issues, contact [e-mail]