> 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/post-get-user-inbox.md). # POST — Get User Inbox ### 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 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. ```json { "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 ```bash 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` ```json { "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: ```json { "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](https://claude.ai/chat/c7705346-165d-410a-9076-4b6f4eecbd2c#) — Retrieve approved WhatsApp templates for your bot. * [POST — Send WhatsApp Message](https://claude.ai/chat/c7705346-165d-410a-9076-4b6f4eecbd2c#) — Send a message to a specific contact. * [POST — Send WhatsApp Template Message](https://claude.ai/chat/c7705346-165d-410a-9076-4b6f4eecbd2c#) — Send a template message to a contact. * [API Authentication Guide](https://claude.ai/chat/c7705346-165d-410a-9076-4b6f4eecbd2c#) — How to obtain and manage your API token. *** *For questions or issues, contact* [*support@botpenguin.com*](mailto:support@botpenguin.com)