> 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) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.botpenguin.com/api-documentation/contacts-and-chats-apis/post-get-user-inbox.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.