> 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)