> 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/get-segments-groups.md). # GET — Segments / Groups ### Overview | Property | Details | | ----------------- | ---------------------------------------------- | | **Method** | `GET` | | **Endpoint** | `https://api.v7.botpenguin.com/inbox/segments` | | **Base URL** | `https://api.v7.botpenguin.com` | | **API Version** | v7 | | **Auth Required** | Yes — Bearer Token | | **Content-Type** | `application/json` | *** ### Authentication | Header | Required | Value | | --------------- | -------- | ----------------------- | | `Authorization` | ✅ Yes | `Bearer YOUR_API_TOKEN` | | `authtype` | ✅ Yes | `Key` | *** ### Request #### Headers | Header | Required | Value | | --------------- | -------- | ----------------------- | | `Authorization` | ✅ Yes | `Bearer YOUR_API_TOKEN` | | `authtype` | ✅ Yes | `Key` | | `Content-Type` | ✅ Yes | `application/json` | No query parameters or request body required. #### Example Request ```bash curl 'https://api.v7.botpenguin.com/inbox/segments' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'authtype: Key' \ -H 'Content-Type: application/json' ``` *** ### Response #### Success — `200 OK` ```json { "success": true, "message": "", "code": 200, "data": [ { "_id": "6a193cf7b50b5c2fac807d1f", "_customer": "5fed38e56fb193dcc6c933f5", "segmentName": "234567", "filters": { "applicableFilters": ["isSubscriber"], "_botWebsite": [], "_botWhatsapp": [], "_botTelegram": [], "_botFacebook": [], "_botAutomation": [], "_agentAssigned": [], "isOnline": false, "status": [], "lastSeenAt": { "startAt": "", "endsAt": "" }, "createdAt": { "startAt": "", "endsAt": "" }, "tags": [], "tagsV2": [], "userInteracted": false, "lastMessageBy": [], "isSubscriber": true, "segments": [], "isLiveChatActive": false, "ctwaNewUsers": false, "ctwaOldUsers": false }, "status": "ACTIVE", "createdAt": "2026-05-29T07:15:03.218Z", "updatedAt": "2026-05-29T07:15:07.654Z", "__v": 0, "totalContacts": 1945 }, { "_id": "694e131dd39d308144af3e20", "_customer": "5fed38e56fb193dcc6c933f5", "segmentName": "Testing Group -2", "filters": { "applicableFilters": ["bots", "tagsV2", "isSubscriber"], "_botWebsite": [], "_botWhatsapp": ["694bee6ac275d8a9c13fb8e1"], "_botTelegram": [], "_botFacebook": [], "_botAutomation": [], "_agentAssigned": [], "isOnline": false, "status": [], "lastSeenAt": { "startAt": "", "endsAt": "" }, "createdAt": { "startAt": "", "endsAt": "" }, "tags": [], "tagsV2": [ { "filters": [ { "operator": "is", "tags": ["BotPenguin Team"] } ] } ], "userInteracted": false, "lastMessageBy": [], "isSubscriber": true, "segments": [], "isLiveChatActive": false, "ctwaNewUsers": false, "ctwaOldUsers": false }, "status": "ACTIVE", "createdAt": "2025-12-26T04:46:21.305Z", "updatedAt": "2025-12-26T04:46:22.640Z", "__v": 0, "totalContacts": 2 } ] } ``` *** #### 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` | List of all segments configured for the account. | *** **`data[]` — Segment Object** | Field | Type | Description | | --------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `_id` | `string` | Unique identifier of the segment. Use this ID in the `segments` filter of [POST — Get User Inbox](https://claude.ai/chat/c7705346-165d-410a-9076-4b6f4eecbd2c#). | | `_customer` | `string` | ID of the customer account this segment belongs to. | | `segmentName` | `string` | Display name of the segment as set by the user. | | `filters` | `object` | The filtering criteria that define which contacts belong to this segment. See `filters` object below. | | `status` | `string` | Current state of the segment. Value: `ACTIVE`. | | `totalContacts` | `number` | Number of contacts currently matching this segment's filters. | | `createdAt` | `string (ISO 8601)` | Timestamp when the segment was created. | | `updatedAt` | `string (ISO 8601)` | Timestamp when the segment was last updated. | | `__v` | `number` | Internal document version. Not for application use. | *** **`filters` Object** Defines the rules used to evaluate which contacts belong to this segment. | Field | Type | Description | | ------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `applicableFilters` | `array` | Active filter keys applied to this segment. Possible values: `bots`, `tags`, `tagsV2`, `isSubscriber`, `status`, `assignedTo`, `segments`, `lastSeenDate`. Empty array means no filters applied — all contacts qualify. | | `_botWebsite` | `array` | Website bot IDs to filter by. Empty if not filtering by website bot. | | `_botWhatsapp` | `array` | WhatsApp bot IDs to filter by. Empty if not filtering by WhatsApp bot. | | `_botTelegram` | `array` | Telegram bot IDs to filter by. Empty if not filtering by Telegram bot. | | `_botFacebook` | `array` | Facebook bot IDs to filter by. Empty if not filtering by Facebook bot. | | `_botAutomation` | `array` | Instagram/automation bot IDs to filter by. Empty if not applicable. | | `_agentAssigned` | `array` | Agent IDs to filter by assigned agent. Empty if not filtering by agent. | | `isOnline` | `boolean` | `true` to filter only currently online contacts. | | `status` | `array` | Conversation statuses to filter by. Example: `["OPEN"]`. Empty means all statuses. | | `lastSeenAt` | `object` | Date range filter for last seen timestamp. Contains `startAt` and `endsAt` as ISO 8601 strings. Empty strings mean no date restriction. | | `createdAt` | `object` | Date range filter for contact creation timestamp. Contains `startAt` and `endsAt`. Empty strings mean no date restriction. | | `tags` | `array` | Legacy tag filter. Contains tag strings or tag IDs. | | `tagsV2` | `array` | Advanced tag filter. Each entry is an object with a `filters` array containing `operator` (`is`) and `tags` (array of tag names). Multiple `tagsV2` entries apply as AND conditions. | | `userInteracted` | `boolean` | `true` to include only contacts who have sent a message. | | `lastMessageBy` | `array` | Filter by last message sender. Values: `bot`, `user`, `agent`. Empty means all. | | `isSubscriber` | `boolean` | `true` to include only subscribed contacts. | | `unreadMessage` | `boolean` | *(Conditional)* `true` to filter contacts with unread messages. Present only on older segments. | | `segments` | `array` | Segment IDs to nest as sub-filters. Allows segments-within-segments filtering. | | `isLiveChatActive` | `boolean` | `true` to include only contacts with active live chat sessions. | | `ctwaNewUsers` | `boolean` | `true` to filter contacts who are new users from Click-to-WhatsApp ads. | | `ctwaOldUsers` | `boolean` | `true` to filter contacts who are returning users from Click-to-WhatsApp ads. | *** ### HTTP Status Codes | Code | Status | Meaning | | ----- | --------------------- | ------------------------------------------------------ | | `200` | OK | Request succeeded. Segments returned in `data` array. | | `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. *** *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/get-segments-groups.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.