GET — Segments / Groups

Retrieve all groups configured in your BotPenguin account.

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

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

{
  "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.
_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:

{
  "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 [e-mail]